Skip to content

Commit

Permalink
feat(cli/validate): add documentation around --extra-schema
Browse files Browse the repository at this point in the history
  • Loading branch information
@GeorgeMac
GeorgeMac committed Jan 19, 2024
1 parent 0314bad commit 1852d41
Showing 1 changed file with 55 additions and 0 deletions.
55 changes: 55 additions & 0 deletions cli/commands/validate.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,66 @@ flipt validate [flags]
### Options

```
-e, --extra-schema string path to extra schema constraints
-F, --format string output format: json, text (default "text")
-h, --help help for validate
--issue-exit-code int Exit code to use when issues are found (default 1)
```

### Behavior

This command validates Flipt's declarative feature configuration files.
It looks for features flag definitions in the same way as Flipts declarative backends.

Check failure on line 22 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Flipt.Spelling] Check the spelling of 'Flipts'. If the spelling is correct, add this word to the spelling exception list.

Raw Output:
{"message": "[Flipt.Spelling] Check the spelling of 'Flipts'. If the spelling is correct, add this word to the spelling exception list.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 22, "column": 59}}}, "severity": "ERROR"}
Checkout the documentation on [locating flag state](/configuration/storage#locating-flag-state) to learn more about this process.

### Extra Schema

Check warning on line 25 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Titles] 'Extra Schema' should be in sentence case

Raw Output:
{"message": "[Openly.Titles] 'Extra Schema' should be in sentence case", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 25, "column": 5}}}, "severity": "WARNING"}

The flag `--extra-schema` (short form `-e`) can be used to pass additional constraints via a CUE schema file.
This file will be unified with the base schema used within `flipt validate` to ensure the format of Flipt files.

Check warning on line 28 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 28, "column": 11}}}, "severity": "WARNING"}
You can find the base schema [here](https://github.com/flipt-io/flipt/blob/main/internal/cue/flipt.cue).

As an example, take the following flipt `features.yaml` file:

```yaml
flags:
- key: someFeature

Check failure on line 35 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / lint 

Insert `··`
name: Some Feature

Check failure on line 36 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / lint 

Insert `··`
```
Running validate will succeed when provided with a path to this file.

Check warning on line 39 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 39, "column": 18}}}, "severity": "WARNING"}
```console
➜ flipt validate
➜ echo $?
0
```

By default, the flag `description` field is not required. However, imagine that you want to ensure this field is always provided with a non-empty string. You can do this via the `--extra-schema` flag and a CUE definition.

Check failure on line 47 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'isn't' instead of 'is not'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 47, "column": 42}}}, "severity": "ERROR"}
In this instance we're going to create a CUE file named `extended.cue`.

Check warning on line 48 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 48, "column": 18}}}, "severity": "WARNING"}
Within this file we will add a constraint to the `#Flag` CUE definition, which ensures our desired behavior.

Check warning on line 49 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 49, "column": 21}}}, "severity": "WARNING"}

Check warning on line 49 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'our'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'our'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 49, "column": 88}}}, "severity": "WARNING"}

```cue
#Flag: {
description: =~"^.+$"
}
```

This definition ensures that description is both supplied and that the value matches the regular expression.
The regular expression in this example ensures a string with a length of at-least 1 character.

Now when invoking the validate subcommand, we pass the path to this extra CUE definition:

Check failure on line 60 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Flipt.Spelling] Check the spelling of 'subcommand'. If the spelling is correct, add this word to the spelling exception list.

Raw Output:
{"message": "[Flipt.Spelling] Check the spelling of 'subcommand'. If the spelling is correct, add this word to the spelling exception list.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 60, "column": 32}}}, "severity": "ERROR"}

Check warning on line 60 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 60, "column": 44}}}, "severity": "WARNING"}

```console
➜ flipt validate -e extended.cue
Validation failed!

- Message : flags.0.description: incomplete value =~"^.+$"
File : features.yaml
Line : 2
```

Here we see that our additional constraint on description is being validated and described in the output.

Check warning on line 71 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 71, "column": 6}}}, "severity": "WARNING"}

Check warning on line 71 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'our'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'our'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 71, "column": 18}}}, "severity": "WARNING"}

### More Info

See the [flag state](/configuration/storage#flag-state-configuration) section of the documentation for more information.

0 comments on commit 1852d41

Please sign in to comment.