Precious - One Code Quality Tool to Rule Them All

Who doesn't love linters and tidiers (aka pretty printers)? I sure love them. I love them so much that in many of my projects I might have five or ten!

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.

TLDR

Precious is a code quality tool that lets you run all of your linters and tidiers with a single command. It's features include:

• One file, precious.toml, defines all of your linter and tidier commands, as well as what files they operate on.
• Respects VCS ignore files and allows global and per-command excludes.
• Language-agnostic, and it works the same way with single- or multi-language projects.
• Easy integration with commit hooks and CI systems.
• When a command needs to be invoked multiple times with different sets of files (for example, a tidier that runs once per file), that command will be run multiple times in parallel, with one process per CPU.
• Commands can be grouped with labels, for example to just run a subset of commands for commit hooks and all commands 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.

Getting Started

The precious binary has a config init subcommand that will generate a config file for you. This subcommand takes the following flags:

| Flag | Description | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | -a, --auto | Automatically determines what components to create | | -c, <code>‑‑component <COMPONENT></code> | The component(s) to generate config for (see below) | | -p, <code>‑‑path <PATH></code> | The path to which the config file should be written. Defaults to ./precious.toml |

You must pass either --auto or at least one --component. In --auto mode, precious will look at all the files in your project and generate config based on the types of files it finds.

Here's an example for a Rust project:

$> precious config init --component rust --component gitignore --component yaml

Components

The following components are supported:

• go - Generates config for a Go project which uses golangci-lint for linting and tidying.
• perl - Generates config for a Perl project which uses a variety of tools, including perlcritic and perltidy.
• rust - Generates config for a Rust project which uses rustfmt for tidying and clippy for linting.
• shell - Generated config which uses shfmt for tidying and shellcheck for linting.
• gitignore - Generates config to lint and tidy (by sorting) .gitignore files using omegasort.
• markdown - Generates config to lint and tidy Markdown files using prettier.
• toml - Generates config to lint and tidy TOML files using taplo.
• yaml - Generates config to lint and tidy YAML files using prettier.

Examples

This repo's examples directory has precious.toml config files for several languages. Contributions for other languages are welcome!

The config in the examples matches what precious config init generates, and there are comments in the files with more details about how you might change this configuration.

Also check out the example mise.toml config file. You can use mise to create per-repo tool configurations. If you use mise's shell integration, the specific tools for each repo will be added to your path whenever you enter the repo's directory. 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:

| Key | Type | Required? | Description | | --------- | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | exclude | array of strings | no | Each array member is a pattern that will be matched against potential files when precious is run. These patterns are matched in the same way as patterns in a gitignore file. <br> You can use lines starting with a ! to negate the meaning of previous rules in the list, so that anything that matches is not excluded even if it matches previous rules. |

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.

| Value | Description | | ------------ | ---------------------------------------------------------------------- | | "per-file" | Run this command once for each matching file. This is the default. | | "per-dir" | Run this command once for each matching directory. | | "once" | Run this command once. |

There are some experimental options for the invoke key as well. The exact names or the details of how they operate may change in a future release.

| Value | Description | | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | <code> .per‑file‑or‑dir = n </code> | If the number of matching files is less than n, run this command once for each matching file. Otherwise run it once for each matching directory. | | <code> .per‑file‑or‑once = n </code> | If the number of matching files is less than n, run this command once for each matching file. Otherwise run it once. | | <code> .per‑dir‑or‑once = n </code> | If the number of matching directories is less than n, run this command once for each matching directory. Otherwise run it once. |

These are written like this:

[commands.some-command]
invoke.per-file-or-dir = 42

These experimental options are useful for optimizing the speed of running a command. In some cases, a command can be run in multiple ways, and how quickly it comple