Docs: Document fixing issues, project roots, and new features (StyraI…

…nc#1043)

This is a follow-up PR to StyraInc#1035, documenting the new capabilities
of Regal added there

Signed-off-by: Anders Eknert <anders@styra.com>

README.md

@@ -3,8 +3,11 @@
 [![Build Status](https://github.com/styrainc/regal/workflows/Build/badge.svg?branch=main)](https://github.com/styrainc/regal/actions)
 ![OPA v0.68.0](https://openpolicyagent.org/badge/v0.68.0)
 
-Regal is a linter and language server for [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/), helping
-you write better policies and have fun while doing it!
+Regal is a linter and language server for [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/), making
+your Rego magnificent, and you the ruler of rules!
+
+With its extensive set of linter rules, documentation and editor integrations, Regal is the perfect companion for policy
+development, whether you're an experienced Rego developer or just starting out.
 
 <img
   src="/docs/assets/regal-banner.png"
@@ -19,16 +22,11 @@ you write better policies and have fun while doing it!
 
 ## Goals
 
+- Deliver an outstanding policy development experience by providing the best possible tools for that purpose
 - Identify common mistakes, bugs and inefficiencies in Rego policies, and suggest better approaches
 - Provide advice on [best practices](https://github.com/StyraInc/rego-style-guide), coding style, and tooling
 - Allow users, teams and organizations to enforce custom rules on their policy code
 
-Regal rules are to as large extent as possible
-[written in Rego](https://www.styra.com/blog/linting-rego-with-rego/) themselves,
-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.
-
 ## What People Say About Regal
 
 > I really like that at each release of Regal I learn something new!
@@ -156,7 +154,27 @@ Documentation:	https://docs.styra.com/regal/rules/style/prefer-snake-case
 > will likely generate a lot of violations. You can do this by passing the `--disable-category style` flag to
 > `regal lint`.
 
-### Using Regal in your build pipeline!
+### Using Regal in Your Editor
+
+Linting from the command line is a great way to get started with Regal, and even for some experienced developers
+the preferred way to work with the linter. However, not only is Regal a linter, but a full-fledged development
+companion for Rego development!
+
+Integrating Regal in your favorite editor means you'll get immediate feedback from the linter as you work on your
+policies. More than that, it'll unlock a whole new set of features that leverage Regal's
+[language server](#regal-language-server), like context-aware completion suggestions, informative tooltips on hover,
+or go-to-definition.
+
+Elevate your policy development experience with Regal in
+[VS Code](https://marketplace.visualstudio.com/items?itemName=tsandall.opa),
+[Zed](https://github.com/StyraInc/zed-rego), [Neovim](https://docs.styra.com/regal/editor-support#neovim),
+[Helix](https://docs.styra.com/regal/editor-support#helix) and
+[other editors](https://docs.styra.com/regal/editor-support)!
+
+To learn more about the features provided by the Regal language server, see the
+[Language Server](https://docs.styra.com/regal/language-server) page.
+
+### Using Regal in Your Build Pipeline
 
 To ensure Regal's rules are enforced consistently in your project or organization,
 we've made it easy to run Regal as part of your builds.
@@ -356,6 +374,12 @@ ignore:
   files:
     - file1.rego
     - "*_tmp.rego"
+
+project:
+  roots:
+    # declares the 'main' and 'lib/jwt' directories as project roots
+    - main
+    - lib/jwt
 ```
 
 Regal will automatically search for a configuration file (`.regal/config.yaml`) in the current directory, and if not
@@ -509,6 +533,43 @@ for the `regal lint` command:
 
 **Note:** all CLI flags override configuration provided in file.
 
+## Project Roots
+
+While many projects consider the project's root directory (in editors often referred to as **workspace**) their
+"main" directory for policies, some projects may contain code from other languages, policy "subprojects", or multiple
+[bundles](https://www.openpolicyagent.org/docs/latest/management-bundles/). While most of Regal's features works
+independently of this — linting, for example, doesn't consider where in a workspace policies are located as long as
+those locations aren't [ignored](#ignoring-files-globally) — some features, like automatically
+[fixing](https://docs.styra.com/regal/fixing) violations, benefit from knowing when a project contains multiple roots.
+
+To provide an example, consider the
+[directory-package-mismatch](https://docs.styra.com/regal/rules/idiomatic/directory-package-mismatch) rule, which states
+that a file declaring a `package` path like `policy.permissions.users` should also be located in a directory structure
+that mirrors that package, i.e. `policy/permissions/users`. When a violation against this rule is reported, the
+`regal fix` command, or its equivalent [Code Action](#regal-language-server) in editors, may when invoked remediate the
+issue by moving the file to the correct location. But where should the `policy/permissions/users` directory *itself*
+reside?
+
+Normally, the answer to that question would be the **project**, or **workspace** root. But if the file was found
+in a subdirectory containing a **bundle**, the directory naturally belongs under that *bundle's root* instead. The
+`roots` configuration option under the top-level `project` object allows you to tell Regal where these roots are,
+and have features like the `directory-package-mismatch` fixer work as you'd expect.
+
+```yaml
+project:
+  roots:
+    - bundle1
+    - bundle2
+```
+
+The configuration file is not the only way Regal may determine project roots. Other ways include:
+
+- A directory containing a `.manifest` file will automatically be registered as a root
+- A directory containing a `.regal` directory will be registered as a root (this is normally the project root)
+
+If a feature that depends on project roots fails to identify any, it will either fail or fall back on the directory
+in which the command was run.
+
 ## Capabilities
 
 By default, Regal will lint your policies using the

docs/fixing.md

@@ -1,26 +1,105 @@
 # Fixing Violations
 
-For each violation Regal is able to detect, there is a documentation page
-explaining the issue in detail and how to fix it. For example, here's the one for
-the [`prefer-some-in-iteration`](/regal/rules/style/prefer-some-in-iteration) rule.
+For each violation Regal is able to detect, there is a documentation page explaining the issue in detail and how to fix
+it. For example, here's the one for the [`prefer-some-in-iteration`](/regal/rules/style/prefer-some-in-iteration) rule.
 
-Some rules are automatically fixable, meaning that Regal can fix the violation
-for you. To automatically fix all supported violations, run:
+Some rules are **automatically** fixable, meaning that Regal can fix the violation for you. Note that while most fixes
+will make minor changes to the code, some fixes make more significant modifications. As an example, the
+[directory-package-mismatch](https://docs.styra.com/regal/rules/idiomatic/directory-package-mismatch) fix will
+automatically move a file to its idiomatic location based on the package path declared in the file.
 
-```shell
-regal fix <path> [path [...]] [flags]
-```
+:::tip
+Before you make any automated fixes, make sure to commit or stash any other changes you may have done in your project!
+That way you can easily revert the changes if anything goes wrong, and this allows you to review the diff before
+committing the fixes.
+:::
 
 Currently, the following rules are automatically fixable:
 
 - [opa-fmt](/regal/rules/style/opa-fmt)
 - [use-rego-v1](/regal/rules/imports/use-rego-v1)
 - [use-assignment-operator](/regal/rules/style/use-assignment-operator)
 - [no-whitespace-comment](/regal/rules/style/no-whitespace-comment)
+- [directory-package-mismatch](https://docs.styra.com/regal/rules/idiomatic/directory-package-mismatch)
+
+So, how do you go on about automatically fixing reported violations?
+
+## The `regal fix` Command
+
+The first method is to use `regal fix` from the command line. This command can be seen as the remediating counterpart
+to `regal lint`, and most configuration options are the same. For example, a linter rule configured to be ignored by
+the linter will also be ignored by the fixer. Typing `regal fix --help` will show you the available options, as well
+as all the supported "fixers" for your version of Regal. Lets's see what automatically fixing violations looks like!
+
+**Example**: fixing all files in the `bundle` directory:
+
+```shell
+> regal fix bundle
+3 fixes applied:
+In project root: /Users/john/projects/authz/bundle
+
+lib/roles.rego:
+- use-rego-v1
+
+policy.rego -> main/policy.rego:
+- directory-package-mismatch
+- no-whitespace-comment
+```
+
+In the example above, Regal made fixes corresponding to the linter rules `use-rego-v1`, `directory-package-mismatch`,
+and `no-whitespace-comment` in `lib/roles.rego` and `policy.rego`. While the number of fixes applied was reported as 3,
+the number of _violations_ fixed could of course have been higher, as e.g. the `no-whitespace-comment` rule might have
+been violated in multiple places in `policy.rego`. Note also how one of the fixes (`directory-package-mismatch`)
+involved **moving** `policy.rego` to `main/policy.rego`, as that rule requires the file to be in a directory structure
+matching its package path (`package main`).
+
+### Project Roots
+
+All paths are relative to its closest **project root**, as reported in the second line of the output. Most policy
+projects will likely only have one "root", which is the workspace directory itself. More complex projects may however
+host multiple roots inside the workspace, and defining these roots — either by configuration, or by `.manifest` files —
+will in some cases (like the previously mentioned `directory-package-mismatch` fix) help Regal better apply the correct
+fixes. See the documentation on [project roots](https://docs.styra.com/regal#project-roots) for more information.
+
+### Dry Run
+
+Using the `--dry-run` flag is a great way to see what changes will be made without actually applying them. Following our
+example from above, adding the `--dry-run` flag to `regal fix bundle` would have told us beforehand what changes we
+should expect to see. Make it a habit to dry-run your fixes before applying them, and make sure you've commited any
+other changes before running the fixer!
+
+## Fixing Violations in Editors
+
+In addition to the `regal fix` command, users integratiing Regal with their editors can fix violations directly as
+they are reported in the file being edited. This is done by means of Code Actions, which commonly displays a lightbulb
+icon next to where a violation occurs. Clicking on the lightbulb will show a list of available actions, which in Regal's
+case maps directly to the available fix for the violation reported (if any).
+
+Example of code action in VS Code, where available fixes can be listed either by clicking the lightbulb icon to the
+right, or by clicking "Quick Fix..." in the tooltip window:
+
+<img
+  src={require('./assets/lsp/code_action_show.png').default}
+  alt="Screenshot of code action displayed in VS Code"/>
+
+Example of suggested Code Action for the
+[use-assignment-operator](https://docs.styra.com/regal/rules/style/use-assignment-operator) rule. Click to fix!
+
+<img
+  src={require('./assets/lsp/code_action_fix.png').default}
+  alt="Screenshot of code action fix suggestion displayed in VS Code"/>
+
+### Limitations
+
+Compared to `regal fix`, automatically fixing violations in editors has some limitations:
+
+- Normally works on one file at a time, not entire directories
+- No ability to dry-run a fix, but on the other hand, the editor's **Undo** feature will let you easily revert any
+  changes made.
 
 :::tip
-Need to fix individual violations? Checkout the editors Regal supports
-[here](/regal/editor-support).
+If you're curious about using Regal to fix problems directly in your editor, see the docs on editor support
+[here](/regal/editor-support) to learn more!
 :::
 
 ## Community

docs/language-server.md

@@ -137,6 +137,7 @@ Regal currently provides quick fix code actions for the following linter rules:
 - [use-rego-v1](https://docs.styra.com/regal/rules/imports/use-rego-v1)
 - [use-assignment-operator](https://docs.styra.com/regal/rules/style/use-assignment-operator)
 - [no-whitespace-comment](https://docs.styra.com/regal/rules/style/no-whitespace-comment)
+- [directory-package-mismatch](https://docs.styra.com/regal/rules/idiomatic/directory-package-mismatch)
 
 ### Code lenses (Evaluation)