1
0
Fork 0
salty-dog/docs/rules.md

206 lines
3.8 KiB
Markdown
Raw Normal View History

2019-06-16 01:04:20 +00:00
# Rules
Rules apply a schema fragment to a set of nodes selected from the original data.
This is a descriptive standard for rules. The enforced meta-rules for rules [are located here](../rules/salty-dog.yml).
- [Rules](#Rules)
- [File](#File)
- [Schema](#Schema)
- [Env](#Env)
- [Include](#Include)
- [Regexp](#Regexp)
- [Stream](#Stream)
- [Name](#Name)
- [Definitions](#Definitions)
- [Rules](#Rules-1)
- [Name](#Name-1)
- [Desc](#Desc)
- [Level](#Level)
- [Tags](#Tags)
- [Select](#Select)
- [Filter](#Filter)
- [Check](#Check)
- [Module](#Module)
## File
Rules may be loaded from YAML or JSON files, using any extension.
### Schema
The default YAML schema has been extended with some custom types.
#### Env
An environment variable by name.
This can be used in CI environments to compare resources against the current job's branch, commit, or tag.
```yaml
foo: !env CI_COMMIT_SHA
```
#### Include
Include another file as a child of this key. The file must be a single document.
Relative paths are resolved from `__dirname`, but no path sanitization is done to prevent `../`. Include paths should
not be taken from user input.
#### Regexp
A regular expression in a string.
Uses standard JS syntax. Flags are supported.
```yaml
foo: !regexp /a.*b/gu
```
#### Stream
A process stream by name (key in `process`).
One of `stderr`, `stdin`, or `stdout`.
```yaml
logger:
streams:
- level: error
stream: !stream stderr
```
2019-06-16 01:04:20 +00:00
### Name
A unique name, used for logging and as the schema `$id` for definitions.
This _should_ be truly unique, but _must_ be unique within the set of `--rules` loaded.
### Definitions
A dict of schema definitions in objects with string keys.
2019-06-16 01:04:20 +00:00
These are added to the Ajv schema and may be referenced by the file `name` and key:
2019-06-16 01:04:20 +00:00
```yaml
name: foo
2019-06-16 01:04:20 +00:00
definitions:
bar:
type: object
2019-06-16 01:04:20 +00:00
rules:
- name: foobar
check:
type: object
properties:
bin:
$ref: "foo#/definitions/bar"
```
2019-06-16 01:04:20 +00:00
### Rules
2019-06-16 01:04:20 +00:00
A list of rules.
2019-06-16 01:04:20 +00:00
#### Name
2019-06-16 01:04:20 +00:00
The rule name, used for logging and inclusion.
Must be unique within the file or module.
```yaml
rules:
- name: foo
```
#### Desc
The rule description, used for error messages.
Some descriptive string.
```yaml
rules:
- name: foo
desc: foos must not overfoo
```
#### Level
The rule's log level, used for inclusion.
**TODO:** use for log messages
One of `debug`, `info`, `warn`, or `error` in a string.
```yaml
rules:
- name: foo
level: debug
```
#### Tags
A list of tags for the rule, used for inclusion.
```yaml
rules:
- name: foo
tags:
- important
- foo-related
- definitely-not-bar
```
#### Select
2019-06-16 01:04:20 +00:00
JSON path used to select nodes from the data.
This selects a list of potential nodes to be `filter`ed and `check`ed. The default (`$`) selects the root of each
document. Selecting a subset of children allows the `check` schema to cover a small fragment of the document.
Uses [jsonpath-plus syntax](https://www.npmjs.com/package/jsonpath-plus#syntax-through-examples) in a string.
```yaml
rules:
- name: foo
select: '$.spec.template.spec.containers[*]'
```
2019-06-16 01:04:20 +00:00
#### Filter
2019-06-16 01:04:20 +00:00
Schema used to filter selected nodes.
If a node was `select`ed but but does not match this schema, it will be skipped and the rule will check the next node.
2019-06-16 01:04:20 +00:00
Uses [ajv syntax](https://ajv.js.org/keywords.html) in an object.
```yaml
rules:
- name: foo
filter:
# only check objects with the property bar
type: object
required: [bar]
```
#### Check
2019-06-16 01:04:20 +00:00
Schema used to check selected nodes.
2019-06-16 01:04:20 +00:00
This is the body of the rule. If a node does not match this schema, the rule will fail.
Uses [ajv syntax](https://ajv.js.org/keywords.html) in an object.
```yaml
rules:
- name: foo
check:
type: string
```
## Module
**TODO:** load rules from `require`d modules