From ed20570659d0b264f36bc2aa92ae3f3e1a77a795 Mon Sep 17 00:00:00 2001
From: Anders Eknert <anders@styra.com>
Date: Thu, 20 Jul 2023 13:04:04 +0200
Subject: [PATCH] Scaffolding

Add `regal new rule` command to allow quickly getting started working
with custom rules, or builtin rules for Regal itself. See added docs for
more details.

Fixes #206

Signed-off-by: Anders Eknert <anders@styra.com>
---
 bundle/regal/result.rego                      |   4 +-
 cmd/new.go                                    | 245 ++++++++++++++++++
 docs/custom-rules.md                          |  22 ++
 e2e/cli_test.go                               |  50 ++++
 internal/embeds/embeds.go                     |   4 +
 .../embeds/schemas}/regal-ast.json            |   0
 .../embeds/templates/builtin/builtin.rego.tpl |  20 ++
 .../templates/builtin/builtin_test.rego.tpl   |  29 +++
 .../embeds/templates/custom/custom.rego.tpl   |  22 ++
 .../templates/custom/custom_test.rego.tpl     |  26 ++
 internal/test/rego_test.go                    |   2 +-
 main.go                                       |   4 -
 12 files changed, 421 insertions(+), 7 deletions(-)
 create mode 100644 cmd/new.go
 rename {schemas => internal/embeds/schemas}/regal-ast.json (100%)
 create mode 100644 internal/embeds/templates/builtin/builtin.rego.tpl
 create mode 100644 internal/embeds/templates/builtin/builtin_test.rego.tpl
 create mode 100644 internal/embeds/templates/custom/custom.rego.tpl
 create mode 100644 internal/embeds/templates/custom/custom_test.rego.tpl

diff --git a/bundle/regal/result.rego b/bundle/regal/result.rego
index c1371bc3..85f98557 100644
--- a/bundle/regal/result.rego
+++ b/bundle/regal/result.rego
@@ -62,7 +62,7 @@ _fail_annotated(metadata, details) := violation if {
 		"level": config.rule_level(config.for_rule(with_location)),
 	})
 
-	without_custom_and_scope := object.remove(with_category, ["custom", "scope"])
+	without_custom_and_scope := object.remove(with_category, ["custom", "scope", "schemas"])
 	related_resources := resource_urls(without_custom_and_scope.related_resources, category)
 
 	violation := json.patch(
@@ -80,7 +80,7 @@ _fail_annotated_custom(metadata, details) := violation if {
 		"level": config.rule_level(config.for_rule(with_location)),
 	})
 
-	violation := object.remove(with_category, ["custom", "scope"])
+	violation := object.remove(with_category, ["custom", "scope", "schemas"])
 }
 
 fail(metadata, details) := _fail_annotated(metadata, details)
diff --git a/cmd/new.go b/cmd/new.go
new file mode 100644
index 00000000..bcedf29a
--- /dev/null
+++ b/cmd/new.go
@@ -0,0 +1,245 @@
+// nolint:wrapcheck
+package cmd
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"text/template"
+
+	"github.com/spf13/cobra"
+
+	"github.com/styrainc/regal/internal/embeds"
+)
+
+// The revive check will warn about using underscore in struct names, but it's seemingly not aware of keywords.
+//
+//nolint:revive
+type newRuleCommandParams struct {
+	type_    string // 'type' is a keyword
+	category string
+	name     string
+	output   string
+}
+
+type TemplateValues struct {
+	Category     string
+	NameOriginal string
+	Name         string
+	NameTest     string
+}
+
+var (
+	categoryRegex = regexp.MustCompile(`^[a-z]+$`)
+	nameRegex     = regexp.MustCompile(`^[a-z_]+[a-z0-9_\-]*$`)
+)
+
+//nolint:lll
+func init() {
+	newCommand := &cobra.Command{
+		Hidden: true,
+		Use:    "new <template>",
+		Long: `Create a new resource according to the chosen template (currently only 'rule' available).
+
+The new command is a development utility for scaffolding new resources for use by Regal.
+
+An example of such a resource would be new linter rules, which could be created either for inclusion in Regal core, or custom rules for your organization or team.`,
+	}
+
+	params := newRuleCommandParams{}
+
+	newRuleCommand := &cobra.Command{
+		Use:   "rule [-t type] [-c category] [-n name]",
+		Short: "Create new rule from template",
+		Long: `Create a new linter rule, for inclusion in Regal or a custom rule for your organization or team.
+
+Example:
+
+regal new rule --type custom --category naming --name camel-case`,
+
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			if params.type_ != "custom" && params.type_ != "builtin" {
+				return fmt.Errorf("type must be 'custom' or 'builtin', got %v", params.type_)
+			}
+
+			if params.category == "" {
+				return fmt.Errorf("category is required for rule")
+			}
+
+			if !categoryRegex.MatchString(params.category) {
+				return fmt.Errorf("category must be a single word, using lowercase letters only")
+			}
+
+			if params.name == "" {
+				return fmt.Errorf("name is required for rule")
+			}
+
+			if !nameRegex.MatchString(params.name) {
+				return fmt.Errorf("name must consist only of lowercase letters, numbers, underscores and dashes")
+			}
+
+			return nil
+		},
+
+		Run: func(_ *cobra.Command, args []string) {
+			if err := scaffoldRule(params); err != nil {
+				log.SetOutput(os.Stderr)
+				log.Println(err)
+				os.Exit(1)
+			}
+		},
+	}
+
+	newRuleCommand.Flags().StringVarP(&params.type_, "type", "t", "custom", "type of rule (custom or builtin)")
+	newRuleCommand.Flags().StringVarP(&params.category, "category", "c", "", "category for rule")
+	newRuleCommand.Flags().StringVarP(&params.name, "name", "n", "", "name of rule")
+	newRuleCommand.Flags().StringVarP(&params.output, "output", "o", "", "output directory")
+
+	newCommand.AddCommand(newRuleCommand)
+	RootCommand.AddCommand(newCommand)
+}
+
+func scaffoldRule(params newRuleCommandParams) error {
+	if params.output == "" {
+		params.output = mustGetWd()
+	}
+
+	if params.type_ == "custom" {
+		return scaffoldCustomRule(params)
+	}
+
+	if params.type_ == "builtin" {
+		return scaffoldBuiltinRule(params)
+	}
+
+	return fmt.Errorf("unsupported type %v", params.type_)
+}
+
+func scaffoldCustomRule(params newRuleCommandParams) error {
+	rulesDir := filepath.Join(params.output, ".regal", "rules", params.category)
+
+	if err := os.MkdirAll(rulesDir, 0o770); err != nil {
+		return err
+	}
+
+	ruleTmpl, err := template.ParseFS(embeds.EmbedTemplatesFS, "templates/custom/custom.rego.tpl")
+	if err != nil {
+		return err
+	}
+
+	ruleFileName := strings.ToLower(strings.ReplaceAll(params.name, "-", "_")) + ".rego"
+
+	ruleFile, err := os.Create(filepath.Join(rulesDir, ruleFileName))
+	if err != nil {
+		return err
+	}
+
+	err = ruleTmpl.Execute(ruleFile, templateValues(params))
+	if err != nil {
+		return err
+	}
+
+	testTmpl, err := template.ParseFS(embeds.EmbedTemplatesFS, "templates/custom/custom_test.rego.tpl")
+	if err != nil {
+		return err
+	}
+
+	testFileName := strings.ToLower(strings.ReplaceAll(params.name, "-", "_")) + "_test.rego"
+
+	testFile, err := os.Create(filepath.Join(rulesDir, testFileName))
+	if err != nil {
+		return err
+	}
+
+	err = testTmpl.Execute(testFile, templateValues(params))
+	if err != nil {
+		return err
+	}
+
+	log.Printf("Created custom rule %q in %s\n", params.name, rulesDir)
+
+	return nil
+}
+
+func scaffoldBuiltinRule(params newRuleCommandParams) error {
+	rulesDir := filepath.Join(params.output, "bundle", "regal", "rules", params.category)
+
+	if err := os.MkdirAll(rulesDir, 0o770); err != nil {
+		return err
+	}
+
+	ruleTmpl, err := template.ParseFS(embeds.EmbedTemplatesFS, "templates/builtin/builtin.rego.tpl")
+	if err != nil {
+		return err
+	}
+
+	ruleFileName := strings.ToLower(strings.ReplaceAll(params.name, "-", "_")) + ".rego"
+
+	ruleFile, err := os.Create(filepath.Join(rulesDir, ruleFileName))
+	if err != nil {
+		return err
+	}
+
+	err = ruleTmpl.Execute(ruleFile, templateValues(params))
+	if err != nil {
+		return err
+	}
+
+	testTmpl, err := template.ParseFS(embeds.EmbedTemplatesFS, "templates/builtin/builtin_test.rego.tpl")
+	if err != nil {
+		return err
+	}
+
+	testFileName := strings.ToLower(strings.ReplaceAll(params.name, "-", "_")) + "_test.rego"
+
+	testFile, err := os.Create(filepath.Join(rulesDir, testFileName))
+	if err != nil {
+		return err
+	}
+
+	err = testTmpl.Execute(testFile, templateValues(params))
+	if err != nil {
+		return err
+	}
+
+	log.Printf("Created builtin rule %q in %s\n", params.name, rulesDir)
+
+	return nil
+}
+
+func templateValues(params newRuleCommandParams) TemplateValues {
+	var tmplNameValue string
+
+	if strings.Contains(params.name, "-") {
+		tmplNameValue = `["` + params.name + `"]`
+	} else {
+		tmplNameValue = "." + params.name
+	}
+
+	var tmplNameTestValue string
+
+	if strings.Contains(params.name, "-") {
+		tmplNameTestValue = `["` + params.name + `_test"]`
+	} else {
+		tmplNameTestValue = "." + params.name + "_test"
+	}
+
+	return TemplateValues{
+		Category:     params.category,
+		NameOriginal: params.name,
+		Name:         tmplNameValue,
+		NameTest:     tmplNameTestValue,
+	}
+}
+
+func mustGetWd() string {
+	wd, err := os.Getwd()
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	return wd
+}
diff --git a/docs/custom-rules.md b/docs/custom-rules.md
index d645f460..bb762f72 100644
--- a/docs/custom-rules.md
+++ b/docs/custom-rules.md
@@ -21,6 +21,28 @@ linter rules might then look something like this:
 If you so prefer, custom rules may also be provided using the `--rules` option for `regal lint`, which may point either
 to a Rego file, or a directory containing Rego files and potentially data (JSON or YAML).
 
+## Creating a New Rule
+
+The simplest way to create a new rule is to use the `regal new rule` command. This command provides scaffolding for
+quickly creating a new rule, including a file for testing. The command has two required arguments: `--category` and
+`--name`, which should be self-explanatory. To create a new custom rule:
+
+```shell
+regal new rule --category naming --name foo-bar-baz
+```
+
+This will create a `.regal/rules` directory in the current working directory, if one does not already exist, and place
+a directory named after `--category` in it, where it will place a policy for the rule, and another one to test it. If
+you'd rather create this directory structure in some other place than the current working directory, you may use the
+`--output` flag to specify a different location. The generated rule includes a simple example, which can be verified by
+running `regal test .regal/rules/${category}`. Modify the rule and the test to suit your needs!
+
+If you'd like to create a new built-in rule for submitting a PR in Regal, you may add the `--type builtin` flag to the
+command (the default is `custom`). This will create a similar scaffolding under `bundle/regal/rules` in the Regal
+repository.
+
+```shell
+
 ## Developing Rules
 
 Regal rules works primarily on the [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) (AST) as
diff --git a/e2e/cli_test.go b/e2e/cli_test.go
index 13950618..b727f93d 100644
--- a/e2e/cli_test.go
+++ b/e2e/cli_test.go
@@ -299,6 +299,56 @@ func TestTestRegalTestWithExtendedASTTypeChecking(t *testing.T) {
 	}
 }
 
+func TestCreateNewCustomRuleFromTemplate(t *testing.T) {
+	t.Parallel()
+
+	stdout := bytes.Buffer{}
+	stderr := bytes.Buffer{}
+
+	tmpDir := t.TempDir()
+
+	err := regal(&stdout, &stderr)("new", "rule", "--category", "naming", "--name", "foo-bar-baz", "--output", tmpDir)
+
+	if exp, act := 0, ExitStatus(err); exp != act {
+		t.Errorf("expected exit status %d, got %d", exp, act)
+	}
+
+	err = regal(&stdout, &stderr)("test", tmpDir)
+
+	if exp, act := 0, ExitStatus(err); exp != act {
+		t.Errorf("expected exit status %d, got %d", exp, act)
+	}
+
+	if strings.HasPrefix(stdout.String(), "PASS 1/1") {
+		t.Errorf("expected stdout to contain PASS 1/1, got %q", stdout.String())
+	}
+}
+
+func TestCreateNewBuiltinRuleFromTemplate(t *testing.T) {
+	t.Parallel()
+
+	stdout := bytes.Buffer{}
+	stderr := bytes.Buffer{}
+
+	tmpDir := t.TempDir()
+
+	err := regal(&stdout, &stderr)("new", "rule", "--category", "naming", "--name", "foo-bar-baz", "--output", tmpDir)
+
+	if exp, act := 0, ExitStatus(err); exp != act {
+		t.Errorf("expected exit status %d, got %d", exp, act)
+	}
+
+	err = regal(&stdout, &stderr)("test", tmpDir)
+
+	if exp, act := 0, ExitStatus(err); exp != act {
+		t.Errorf("expected exit status %d, got %d", exp, act)
+	}
+
+	if strings.HasPrefix(stdout.String(), "PASS 1/1") {
+		t.Errorf("expected stdout to contain PASS 1/1, got %q", stdout.String())
+	}
+}
+
 func binary() string {
 	if b := os.Getenv("REGAL_BIN"); b != "" {
 		return b
diff --git a/internal/embeds/embeds.go b/internal/embeds/embeds.go
index ad2ace5d..4a353935 100644
--- a/internal/embeds/embeds.go
+++ b/internal/embeds/embeds.go
@@ -5,4 +5,8 @@ import "embed"
 
 var EmbedBundleFS embed.FS
 
+//go:embed templates
+var EmbedTemplatesFS embed.FS
+
+//go:embed schemas/regal-ast.json
 var ASTSchema []byte
diff --git a/schemas/regal-ast.json b/internal/embeds/schemas/regal-ast.json
similarity index 100%
rename from schemas/regal-ast.json
rename to internal/embeds/schemas/regal-ast.json
diff --git a/internal/embeds/templates/builtin/builtin.rego.tpl b/internal/embeds/templates/builtin/builtin.rego.tpl
new file mode 100644
index 00000000..3ba87414
--- /dev/null
+++ b/internal/embeds/templates/builtin/builtin.rego.tpl
@@ -0,0 +1,20 @@
+# METADATA
+# description: Add description of rule here!
+package regal.rules.{{.Category}}{{.Name}}
+
+import future.keywords.contains
+import future.keywords.if
+import future.keywords.in
+
+import data.regal.result
+
+report contains violation if {
+	# Or change to imports, packages, comments, etc.
+	some rule in input.rules
+
+	# Deny any rule named foo, bar, or baz. This is just an example!
+	# Add your own rule logic here.
+	rule.head.name in {"foo", "bar", "baz"}
+
+	violation := result.fail(rego.metadata.chain(), result.location(rule))
+}
diff --git a/internal/embeds/templates/builtin/builtin_test.rego.tpl b/internal/embeds/templates/builtin/builtin_test.rego.tpl
new file mode 100644
index 00000000..8ba9d940
--- /dev/null
+++ b/internal/embeds/templates/builtin/builtin_test.rego.tpl
@@ -0,0 +1,29 @@
+package regal.rules.{{.Category}}{{.NameTest}}
+
+import future.keywords.if
+import future.keywords.in
+
+import data.regal.ast
+
+import data.regal.rules.{{.Category}}{{.Name}} as rule
+
+# Example test, replace with your own
+test_rule_named_foo_not_allowed {
+	module := ast.policy("foo := true")
+
+	r := rule.report with input as module
+
+	# Use print(r) here to see the report. Great for development!
+
+	r == {{ "{{" }}
+		"category": "{{.Category}}",
+		"description": "Add description of rule here!",
+		"level": "error",
+		"location": {"col": 1, "file": "policy.rego", "row": 3, "text": "foo := true"},
+		"related_resources": [{
+			"description": "documentation",
+			"ref": "https://github.com/StyraInc/regal/blob/main/docs/rules/{{.Category}}/{{.NameOriginal}}.md"
+		}],
+		"title": "{{.NameOriginal}}"
+	}}
+}
diff --git a/internal/embeds/templates/custom/custom.rego.tpl b/internal/embeds/templates/custom/custom.rego.tpl
new file mode 100644
index 00000000..fc719556
--- /dev/null
+++ b/internal/embeds/templates/custom/custom.rego.tpl
@@ -0,0 +1,22 @@
+# METADATA
+# description: Add description of rule here!
+# schemas:
+# - input: schema.regal.ast
+package custom.regal.rules.{{.Category}}{{.Name}}
+
+import future.keywords.contains
+import future.keywords.if
+import future.keywords.in
+
+import data.regal.result
+
+report contains violation if {
+	# Or change to imports, packages, comments, etc.
+	some rule in input.rules
+
+	# Deny any rule named foo, bar, or baz. This is just an example!
+	# Add your own rule logic here.
+	rule.head.name in {"foo", "bar", "baz"}
+
+	violation := result.fail(rego.metadata.chain(), result.location(rule))
+}
diff --git a/internal/embeds/templates/custom/custom_test.rego.tpl b/internal/embeds/templates/custom/custom_test.rego.tpl
new file mode 100644
index 00000000..ed49c144
--- /dev/null
+++ b/internal/embeds/templates/custom/custom_test.rego.tpl
@@ -0,0 +1,26 @@
+package custom.regal.rules.{{.Category}}{{.NameTest}}
+
+import future.keywords.if
+import future.keywords.in
+
+import data.custom.regal.rules.{{.Category}}{{.Name}} as rule
+
+# Example test, replace with your own
+test_rule_named_foo_not_allowed {
+    module := regal.parse_module("example.rego", `
+    package policy
+
+    foo := true`)
+
+    r := rule.report with input as module
+
+    # Use print(r) here to see the report. Great for development!
+
+    r == {{ "{{" }}
+    	"category": "{{.Category}}",
+    	"description": "Add description of rule here!",
+    	"level": "error",
+    	"location": {"col": 5, "file": "example.rego", "row": 4, "text": "    foo := true"},
+    	"title": "{{.NameOriginal}}"
+    }}
+}
diff --git a/internal/test/rego_test.go b/internal/test/rego_test.go
index 3dc4df4b..2fbc8b67 100644
--- a/internal/test/rego_test.go
+++ b/internal/test/rego_test.go
@@ -40,7 +40,7 @@ func TestRunRegoUnitTests(t *testing.T) {
 		store.Abort(ctx, txn)
 	})
 
-	schema, err := os.ReadFile("../../schemas/regal-ast.json")
+	schema, err := os.ReadFile("../embeds/schemas/regal-ast.json")
 	if err != nil {
 		t.Fatal(err)
 	}
diff --git a/main.go b/main.go
index f81c569e..e3cd4b36 100644
--- a/main.go
+++ b/main.go
@@ -15,9 +15,6 @@ import (
 //go:embed all:bundle
 var bundle embed.FS
 
-//go:embed schemas/regal-ast.json
-var schema []byte
-
 func main() {
 	// Remove date and time from any `log.*` calls, as that doesn't add much of value here
 	// Evaluate options for logging later..
@@ -27,7 +24,6 @@ func main() {
 	// so while this isn't pretty, we'll use a separate package to carry state from here. If you
 	// know of a better way of doing this, don't hesitate to fix this.
 	embeds.EmbedBundleFS = bundle
-	embeds.ASTSchema = schema
 
 	if err := cmd.RootCommand.Execute(); err != nil {
 		os.Exit(1)