Precious - One Code Quality Tool to Rule Them All

Who doesn't love linters and tidiers? I sure love them. I love them so much that in many of my projects I might easily have five or ten of them enabled!

Wouldn't it be great if you could run all of them with just one command? Wouldn't it be great if that command just had one config file to define what tools to run on each part of your project? Wouldn't it be great if Sauron were our ruler?

Now with Precious you can say "yes" to all of those questions.

Why Precious?

In all seriousness, managing code quality tools can be a bit of a pain. It becomes much more painful when you have a multi-language project. You may have multiple tools per language, each of which runs on some subset of your codebase. Then you need to hook these tools into your commit hooks and CI system.

With Precious you can configure all of your code quality tool rules in one place and easily run precious from your commit hooks and in CI.

Installation

There are several ways to install this tool.

Use ubi

Install my universal binary installer (ubi) tool and you can use it to download precious and many other tools.

$> ubi --project houseabsolute/precious --in ~/bin

Binary Releases

You can grab a binary release from the releases page. Untar the tarball and put the executable it contains somewhere in your path and you're good to go.

Cargo

You can also install this via cargo by running cargo install precious. See the cargo documentation to understand where the binary will be installed.

Examples

Check out this repo's examples directory, which has precious.toml config files for several languages. Contributions for other languages are welcome!

Also check out the example install-dev-tools.sh script. You can customize this as needed to install only the tools you need for your project.

Configuration

Precious is configured via a single precious.toml or .precious.toml file that lives in your project root. The file is in TOML format.

There is just one key that can be set in the top level table of the config file:

All other configuration is on a per-command basis. A command is something that either tidies (aka pretty prints or beautifies), lints, or does both. These commands are external programs which precious will execute as needed.

Each command is defined in a block named something like [commands.command-name]. Each name after the commands. prefix must be unique. You can have run the same executable differently with different commands as long as each command has a unique name.

Commands are run in the same order as they appear in the config file.

Command Invocation

There are three configuration keys for command invocation. All of them are optional. If none are specified, precious defaults to this:

invoke      = "per-file"
working_dir = "root"
path_args   = "file"

This runs the command once per file with the working directory for the command as the project root. The command will be passed a relative path to the file from the root as a single argument to the command.

invoke

The invoke key tells precious how the command should be invoked.

working_dir

The working_dir key tells precious what the working directory should be when the command is run.

working_dir.chdir_to = "path"

The final option for working_dir is to set an explicit path as the working directory.

With this option, the working directory will be set to the given subdirectory when the command is executed. Relative paths passed to the command will be relative to this subdirectory rather than the project root.

path_args

The path_args key tells precious how paths should be passed when the command is run.

Nonsensical Combinations

Most combinations of these configuration keys are allowed, but there are some nonsensical combinations that will cause precious to exit with an error.

invoke = "per-file"
path_args = "dir", "none", "dot", or "absolute-dir"

You cannot invoke a command once per file without passing the filename.

invoke = "per-dir"
path_args = "none" or "dot"
working_dir = "root"
# ... or ...
working_dir.chdir_to = "whatever"

You cannot invoke a command once per directory from a root without passing the directory name or a list of file names. If you want to run a command once per directory with no path arguments or using . as the path then you must set working_dir = "dir".

invoke = "once"
working_dir = "dir"

You cannot invoke a command once if the working directory is set to each matching directory in turn.

Invocation Examples

See the Invocation Examples documentation for comprehensive examples of every possible set of options.

Other Per-Command Configuration Keys

The other keys allowed for each command are as follows:

Referencing the Project Root

For commands that can be run from a subdirectory, you may need to specify config files in terms of the project root. You can do this by using the string $PRECIOUS_ROOT in any element of the cmd configuration key. So for example you might write something like this:

cmd = ["some-tidier", "--config", "$PRECIOUS_ROOT/some-tidier.conf"]

The $PRECIOUS_ROOT string will be replaced by the absolute path to the project root.

Running Precious

To get help run precious --help.

The root command takes the following options:

Parallel Execution

Precious will always execute commands in parallel, with one process per CPU by default. The execution is parallelized based on the command's invocation configuration. For example, on a 12 CPU system, a command that has invoke = "per-file" will be executed up to 12 times in parallel, with each command execution receiving one file.

You can disable parallel execution by passing --jobs 1.

Subcommands

The precious command has two subcommands, lint and tidy. You must always specify one of these. These subcommands take the same options.

Selecting Paths to Operate On

When you run precious you must tell it what paths to operate on. There are several options for this:

Running One Command

You can tidy or lint with just a single command by passing the --command flag:

$> precious lint --command some-command --all

The name passed to --command must match the name of the command in your config file. So in the above example, this would look for a command defined as [commands.some-command] in your config.

Selecting Commands With Labels

Each command can be assigned one or more labels. This lets you create arbitrary groups of commands. Then when you tidy or lint you can pick a label by passing a --label flag:

$> precious lint --label some-label --all

The way labels work is as follows:

• A command without a labels key in its config has one label, default.
• Running tidy or lint without a --label flag uses the default label.
• If you assign labels to a command and you want that command included in the default label, you must explicitly include it:

  [command.some-command]
  # ...
  labels = [ "default", "some-label" ]
  

Default Exclusions

When selecting paths precious always respects your ignore files. Right now it only knows how this works for git, and it will respect all of the following ignore files:

• Per-directory .ignore and .gitignore files.
• The .git/info/exclude file.
• Global gitignore globs, usually found in $XDG_CONFIG_HOME/git/ignore.

This is implemented using the rust ignore crate, so adding support for other VCS systems should be proposed there.

In addition, you can specify excludes for all commands by setting a global exclude key.

Finally, you can specify per-command include and exclude keys.

How Include and Exclude Are Applied

When precious runs it does the following to determine which commands apply to which paths.

• The base files to operate on are selected based on the command line option specified. This is one of:
  • --all - All files under the project root (the directory containing the precious config file).
  • --git - All files in the git repo that have been modified, including staged files.
  • --staged - All files in the git repo that have been staged.
  • paths passed on the CLI - If a path is a file it is added to the list as-is. If the path is a directory then all the files under that directory (recursively) are found.
• VCS ignore rules are applied to remove files from this list.
• The global exclude rules are applied to remove files from this list.
• Based on the command's invoke key, a list of files to be checked is generated and the command's include/exclude rules are applied. To be included, a file must match at least one include rule and not match any exclude rules to be accepted.
  • If invoke is per-file, then the rules are applied one file at a time.
  • If invoke is per-dir, then if any file in the directory matches the rules, the command will be run on that directory.
  • If invoke is once, then the rules are applied to all of the files at once. If any one of those files matches the include rule, the command will be run.

Configuration Recommendations

Here are some recommendations for how to get the best experience with precious.

Choosing How to invoke the Command

Some commands might work equally well with invoke set to either per-dir or root. The right run mode to choose depends on how you are using precious.

In general, if you either have a very small set of directories, or you are running precious on most or all of the directories at once, then once will be faster.

However, if you have a larger set of directories and you usually only need to lint or tidy a small subset of these at once, then per-dir mode will be faster.

Quiet Flags

Many commands will accept a "quiet" flag of some sort. In general, you probably do not want to run commands in a quiet mode with precious.

In the case of a successful tidy or lint command execution, precious already hides all stdout from the command that it runs. If the command fails somehow, precious will print out the command's stdout and stderr output.

By default, precious treats any output to stderr as an error in the command (as opposed to a linting failure). You can use the ignore_stderr to specify one or more regexes for allowed stderr output.

In addition, you can see all stdout and stderr output from a comment by running precious in --debug mode.

All of which is to say that in general there's no value to running a command in quiet mode with precious. All that does is make it harder to debug issues with that command when lint checks fail or other issues occur.

Exit Codes

When running in --tidy mode, precious always exits with 0, whether or not any files are tidied.

When running in --lint mode, precious will exit with 0 when all files pass linting. If any lint commands fail it will exit with 1.

In both modes, if any commands fail, either by returning exit codes that aren't listed as ok or by printing to stderr unexpectedly, then precious will exit with a non-0 exit code.

Common Scenarios

There are some configuration scenarios that you may need to handle. Here are some examples:

Command runs just once for the entire source tree

Some commands, such as rust-clippy, expect to run just once across the entire source tree, rather than once per file or directory.

In order to make that happen you should use the following config:

include = "**/*.rs"
invoke = "once"
path_args = "dot" # or "none"

This will cause precious to run the command exactly once in the project root.

Command runs in the same directory as the files it lints and does not accept path as arguments

If you want to run the command without passing the path being operated on to the command, set invoke = "per-dir" and path_args = "none":

include   = "**/*.rs"
invoke    = "per-dir"
path_args = "none"

You want a command to exclude an entire directory (tree) except for one or more files

Use an ignore pattern starting with ! in the exclude list:

[commands.rustfmt]
type    = "both"
include = "**/*.rs"
exclude = [
    "path/to/dir",
    "!path/to/dir/included.rs",
]
cmd     = ["rustfmt"]
lint_flags = "--check"
ok_exit_codes = [0]
lint_failure_exit_codes = [1]

You want to run Precious as a commit hook

Simply run precious lint -s in your hook. It will exit with a non-zero status if any of the lint commands indicate a linting problem.

You want to run commands in a specific order

As of version 0.1.2, commands are run in the same order as they appear in the config file.

Build Status

Build and Test

Cargo Audit Nightly

Cargo Audit On Push