Vale is a command-line tool that brings code-like linting to prose. Vale is cross-platform (Windows, macOS, and Linux), written in Go, and available on GitHub.
.vale.ini is the configuration file, located in the project root.
This file defines what to lint, what linting rules to apply, and the global alert threshold that should be reported.
The .github/vale folder contains the linting rules themselves
(each defined in YAML - much like Velociraptor artifacts), plus
support files such as dictionaries and “views” definitions that
allow the rules to operate on non-standard files such as YAML.
The same .github/vale
(https://github.com/Velocidex/velociraptor-vale) is used across
projects, thus ensuring consistency, but the .vale.ini is specific
to each project since the linting targets vary.
The vale repo is referenced in each project as a git submodule. This means that a normal clone of any repo will not automatically have these files. To include these files when cloning you either need to run:
git clone --recurse-submodules <main-repo-url>
or else run:
git submodule update --remote --recursive
after cloning, to pull in the submodule contents.
Once that’s done, you will already have the files and folders necessary to run all the Vale tests. All you need to do is ensure that you have the Vale binary in your path on your computer so that you can actually run it. Vale is a Go program that has no external dependencies.
Install the latest vale binary into your path. Test it by running
vale --ls-dirs or vale version.
NOTE: despite what Vale’s documentation says, you DO NOT need to
run vale sync and you shouldn’t do so. We don’t use external
styles and therefore don’t need anything outside of our own repo.
Everything you need, except for the Vale binary, is already in the
repo.
cd to the project root - when you run Vale it will look for the
.vale.ini file in the CWD, which in turn will tell Vale where
to find the Vale “styles” directory (which is .github/vale).
Run vale . is all you need to do to perform all the checks.
Vale’s default output is usually fine, but for particular types of
tasks you might want to try the custom output templates in
vale/config/templates.
Some templates generate more concise output (useful for feeding into other CLI apps) and some are just more human-friendly.
Use them with the --output flag, for example:
vale . --output=collate.tmpl
Vale also has a native JSON output format that you might find
useful because it dumps all fields:
vale . --output="JSON"