ssube
/
salty-dog
1
0
Fork 0
Code

docs: clean up ToCs

This commit is contained in:
ssube 2019-06-29 18:02:58 -05:00
parent 680993a88e
commit 901696f8f0
2 changed files with 56 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/index.md
View File

@ -2,6 +2,15 @@
Rule-based YAML validator using JSON schemas. Rule-based YAML validator using JSON schemas.
- [Salty Dog](#Salty-Dog)
- [Rules](#Rules)
- [Usage](#Usage)
- [Docker](#Docker)
- [Interactive](#Interactive)
- [Node](#Node)
- [Global](#Global)
- [Local](#Local)
## Rules ## Rules
Rules can be loaded from YAML files or Node modules and [are documented here](./rules.md). Rules can be loaded from YAML files or Node modules and [are documented here](./rules.md).

81
docs/rules.md
View File

@ -5,33 +5,33 @@ 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). This is a descriptive standard for rules. The enforced meta-rules for rules [are located here](../rules/salty-dog.yml).
- [Rules](#Rules) - [Rules](#Rules)
- [File](#File) - [From File](#From-File)
- [Schema](#Schema) - [YAML Schema](#YAML-Schema)
- [Env](#Env) - [Env Type](#Env-Type)
- [Include](#Include) - [Include Type](#Include-Type)
- [Regexp](#Regexp) - [Regexp Type](#Regexp-Type)
- [Stream](#Stream) - [Stream Type](#Stream-Type)
- [Name](#Name) - [File Name](#File-Name)
- [Definitions](#Definitions) - [Schema Definitions](#Schema-Definitions)
- [Rules](#Rules-1) - [Rule Definitions](#Rule-Definitions)
- [Name](#Name-1) - [Rule Name](#Rule-Name)
- [Desc](#Desc) - [Rule Description](#Rule-Description)
- [Level](#Level) - [Rule Level](#Rule-Level)
- [Tags](#Tags) - [Rule Tags](#Rule-Tags)
- [Select](#Select) - [Rule Selector](#Rule-Selector)
- [Filter](#Filter) - [Rule Filter](#Rule-Filter)
- [Check](#Check) - [Rule Check](#Rule-Check)
- [Module](#Module) - [From Module](#From-Module)
## File ## From File
Rules may be loaded from YAML or JSON files, using any extension. Rules may be loaded from YAML or JSON files, using any extension.
### Schema ### YAML Schema
The default YAML schema has been extended with some custom types. The default YAML schema has been extended with some custom types.
#### Env #### Env Type
An environment variable by name. An environment variable by name.
@ -41,14 +41,14 @@ This can be used in CI environments to compare resources against the current job
foo: !env CI_COMMIT_SHA foo: !env CI_COMMIT_SHA
``` ```
#### Include #### Include Type
Include another file as a child of this key. The file must be a single document. 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 Relative paths are resolved from `__dirname`, but no path sanitization is done to prevent `../`. Include paths should
not be taken from user input. not be taken from user input.
#### Regexp #### Regexp Type
A regular expression in a string. A regular expression in a string.
@ -58,7 +58,7 @@ Uses standard JS syntax. Flags are supported.
foo: !regexp /a.*b/gu foo: !regexp /a.*b/gu
``` ```
#### Stream #### Stream Type
A process stream by name (key in `process`). A process stream by name (key in `process`).
@ -71,13 +71,17 @@ logger:
stream: !stream stderr stream: !stream stderr
``` ```
### Name ### File Name
A unique name, used for logging and as the schema `$id` for definitions. 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. This _should_ be truly unique, but _must_ be unique within the set of `--rules` loaded.
### Definitions ```yaml
name: foo-rules
```
### Schema Definitions
A dict of schema definitions in objects with string keys. A dict of schema definitions in objects with string keys.
@ -99,11 +103,20 @@ rules:
$ref: "foo#/definitions/bar" $ref: "foo#/definitions/bar"
``` ```
### Rules ### Rule Definitions
A list of rules. A list of rules.
#### Name ```yaml
name: foo
rules:
- name: foobar
check:
type: object
```
#### Rule Name
The rule name, used for logging and inclusion. The rule name, used for logging and inclusion.
@ -114,7 +127,7 @@ rules:
- name: foo - name: foo
``` ```
#### Desc #### Rule Description
The rule description, used for error messages. The rule description, used for error messages.
@ -126,7 +139,7 @@ rules:
desc: foos must not overfoo desc: foos must not overfoo
``` ```
#### Level #### Rule Level
The rule's log level, used for inclusion. The rule's log level, used for inclusion.
@ -140,7 +153,7 @@ rules:
level: debug level: debug
``` ```
#### Tags #### Rule Tags
A list of tags for the rule, used for inclusion. A list of tags for the rule, used for inclusion.
@ -153,7 +166,7 @@ rules:
- definitely-not-bar - definitely-not-bar
``` ```
#### Select #### Rule Selector
JSON path used to select nodes from the data. JSON path used to select nodes from the data.
@ -168,7 +181,7 @@ rules:
select: '$.spec.template.spec.containers[*]' select: '$.spec.template.spec.containers[*]'
``` ```
#### Filter #### Rule Filter
Schema used to filter selected nodes. Schema used to filter selected nodes.
@ -186,7 +199,7 @@ rules:
required: [bar] required: [bar]
``` ```
#### Check #### Rule Check
Schema used to check selected nodes. Schema used to check selected nodes.
@ -201,6 +214,6 @@ rules:
type: string type: string
``` ```
## Module ## From Module
**TODO:** load rules from `require`d modules **TODO:** load rules from `require`d modules