Skip to content

Commit

Permalink
docs: correct line length
Browse files Browse the repository at this point in the history 
Signed-off-by: Charlie Egan <[email protected]>
  • Loading branch information
@charlieegan3
charlieegan3 committed Jan 6, 2025
1 parent 7d97f96 commit b3e8ab5
Showing 1 changed file with 52 additions and 39 deletions.
91 changes: 52 additions & 39 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ See the [adopters](/docs/adopters.md) file for more Regal users.
### Download Regal

**MacOS and Linux**

```shell
brew install styrainc/packages/regal
```
Expand All @@ -68,40 +69,47 @@ for a list of package repositories which distribute Regal.
Manual installation commands:

**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"
```

**Docker**

```shell
docker pull ghcr.io/styrainc/regal:latest
```

See all versions, and checksum files, at the Regal [releases](https://github.com/StyraInc/regal/releases/) page, and
published Docker images at the [packages](https://github.com/StyraInc/regal/pkgs/container/regal) page.

</details>

### Try it out!

First, author some Rego!

**policy/authz.rego**

```rego
package authz
Expand All @@ -122,8 +130,10 @@ Next, run `regal lint` pointed at one or more files or directories to have them
```shell
regal lint policy/
```

<!-- markdownlint-capture -->
<!-- markdownlint-disable MD010 -->

```text
Rule: non-raw-regex-pattern
Description: Use raw strings for regex patterns
Expand All @@ -148,6 +158,7 @@ Documentation: https://docs.styra.com/regal/rules/style/prefer-snake-case
1 file linted. 3 violations found.
```

<!-- markdownlint-restore -->
<br />

Expand Down Expand Up @@ -198,8 +209,8 @@ The following rules are currently available:

<!-- RULES_TABLE_START -->

| Category | Title | Description |
|-------------|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| Category | Title | Description |
| ----------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| bugs | [annotation-without-metadata](https://docs.styra.com/regal/rules/bugs/annotation-without-metadata) | Annotation without metadata |
| bugs | [argument-always-wildcard](https://docs.styra.com/regal/rules/bugs/argument-always-wildcard) | Argument is always a wildcard |
| bugs | [constant-condition](https://docs.styra.com/regal/rules/bugs/constant-condition) | Constant condition |
Expand Down Expand Up @@ -298,7 +309,7 @@ By default, all rules except for those in the `custom` category are currently **

Most Regal rules will use data only from a single file at a time, with no consideration for other files. A few rules
however require data from multiple files, and will therefore collect, or aggregate, data from all files provided for
linting. These rules are called *aggregate rules*, and will only be run when there is more than one file to lint, such
linting. These rules are called _aggregate rules_, and will only be run when there is more than one file to lint, such
as when linting a directory or a whole policy repository. One example of such a rule is the `prefer-package-imports`
rule, which will aggregate package names and imports from all provided policies in order to determine if any imports
are pointing to rules or functions rather than packages. You normally won't need to care about this distinction other
Expand Down Expand Up @@ -327,14 +338,15 @@ A custom configuration file may be used to override the [default configuration](
options provided by Regal. The most common use case for this is to change the severity level of a rule. These three
levels are available:

- `ignore` — disable the rule entirely
- `ignore` — disable the rule entirely
- `warning` — report the violation without changing the exit code of the lint command
- `error` — report the violation and have the lint command exit with a non-zero exit code (default)
- `error` — report the violation and have the lint command exit with a non-zero exit code (default)

Additionally, some rules may have configuration options of their own. See the documentation page for a rule to learn
more about it.

**.regal/config.yaml**

```yaml
rules:
style:
Expand All @@ -354,16 +366,16 @@ rules:
# in this example, test files are ignored
ignore:
files:
- "*_test.rego"
- "*_test.rego"
custom:
# custom rule configuration
naming-convention:
level: error
conventions:
# ensure all package names start with "acmecorp" or "system"
- pattern: '^acmecorp\.[a-z_\.]+$|^system\.[a-z_\.]+$'
targets:
- package
# ensure all package names start with "acmecorp" or "system"
- pattern: '^acmecorp\.[a-z_\.]+$|^system\.[a-z_\.]+$'
targets:
- package

capabilities:
from:
Expand All @@ -379,14 +391,14 @@ capabilities:
ignore:
# files can be excluded from all lint rules according to glob-patterns
files:
- file1.rego
- "*_tmp.rego"
- file1.rego
- "*_tmp.rego"

project:
roots:
# declares the 'main' and 'lib/jwt' directories as project roots
- main
- lib/jwt
# 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
Expand Down Expand Up @@ -477,10 +489,10 @@ rules:
level: error
ignore:
files:
# ignore line length in test files to accommodate messy test data
- "*_test.rego"
# specific file used only for testing
- "scratch.rego"
# ignore line length in test files to accommodate messy test data
- "*_test.rego"
# specific file used only for testing
- "scratch.rego"
```

### Ignoring Files Globally
Expand All @@ -495,8 +507,8 @@ If you want to ignore certain files for all rules, you can use the global ignore
```yaml
ignore:
files:
- file1.rego
- "*_tmp.rego"
- file1.rego
- "*_tmp.rego"
```

### Inline Ignore Directives
Expand Down Expand Up @@ -554,19 +566,19 @@ To provide an example, consider the
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*
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
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
- bundle1
- bundle2
```

The configuration file is not the only way Regal may determine project roots. Other ways include:
Expand Down Expand Up @@ -620,18 +632,18 @@ capabilities:
version: v0.58.0
minus:
builtins:
# exclude rules that depend on the http.send built-in function
- name: http.send
# exclude rules that depend on the http.send built-in function
- name: http.send
plus:
builtins:
# make Regal aware of a custom "ldap.query" function
- name: ldap.query
type: function
decl:
args:
- type: string
result:
type: object
# make Regal aware of a custom "ldap.query" function
- name: ldap.query
type: function
decl:
args:
- type: string
result:
type: object
```

### Loading Capabilities from URLs
Expand All @@ -650,9 +662,9 @@ capabilities:

Regal includes capabilities files for the following engines:

| Engine | Website | Description |
|--------|---------|-------------|
| `opa` | [OPA website](https://www.openpolicyagent.org/) | Open Policy Agent |
| Engine | Website | Description |
| ------ | --------------------------------------------------------------- | -------------------- |
| `opa` | [OPA website](https://www.openpolicyagent.org/) | Open Policy Agent |
| `eopa` | [Enterprise OPA website](https://www.styra.com/enterprise-opa/) | Styra Enterprise OPA |

## Exit Codes
Expand Down Expand Up @@ -775,7 +787,8 @@ See the [Editor Support](/docs/editor-support.md) page for information about Reg
by Charlie Egan ([@charlieegan3](https://github.com/charlieegan3))
- [Linting Rego with... Rego!](https://www.styra.com/blog/linting-rego-with-rego/) by Anders Eknert ([@anderseknert](https://github.com/anderseknert))
- [Regal: Rego(OPA)用リンタの導入手順](https://zenn.dev/erueru_tech/articles/6cfb886d92858a) by Jun Fujita ([@erueru-tech](https://github.com/erueru-tech))
- [Regal を使って Rego を Lint する](https://tech.dentsusoken.com/entry/2024/12/05/Regal_%E3%82%92%E4%BD%BF%E3%81%A3%E3%81%A6_Rego_%E3%82%92_Lint_%E3%81%99%E3%82%8B) by Shibata Takao ([@shibata.takao](https://shodo.ink/@shibata.takao/))
- [Regal を使って Rego を Lint する](https://tech.dentsusoken.com/entry/2024/12/05/Regal_%E3%82%92%E4%BD%BF%E3%81%A3%E3%81%A6_Rego_%E3%82%92_Lint_%E3%81%99%E3%82%8B)
by Shibata Takao ([@shibata.takao](https://shodo.ink/@shibata.takao/))

## Status

Expand Down

0 comments on commit b3e8ab5

Please sign in to comment.