珍贵 - 一款统管所有代码质量的工具

谁不喜欢代码检查器和格式化工具（即美化打印器）呢？我当然喜欢。我非常喜欢它们，以至于在我的许多项目中可能有五到十个！

如果只需一个命令就可以运行所有这些工具，那岂不是很好？如果这个命令只需一个配置文件来定义在每个项目的哪个部分运行哪些工具，那岂不是很好？如果索伦是我们的统治者，那岂不是很好？

现在，有了Precious，你可以对上述所有问题说“是的”。

TLDR

Precious是一款代码质量工具，允许您使用单个命令运行所有代码检查器和格式化工具。其功能包括

• 一个文件，precious.toml，定义了所有代码检查器和格式化工具的命令以及它们操作的文件。
• 尊重版本控制系统忽略文件，并允许全局和按命令排除。
• 语言无关，与单语言或多语言项目的工作方式相同。
• 易于与提交钩子和CI系统集成。
• 默认情况下，命令并行执行，每个CPU一个进程。
• 可以使用标签对命令进行分组，例如，仅运行提交钩子的一部分命令和CI中的所有命令。

安装

安装此工具有几种方法。

使用ubi

安装我的通用二进制安装程序（ubi）工具，然后您可以使用它下载precious和其他许多工具。

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

二进制发布版

您可以从发布页面获取二进制发布版。解压缩tarball，将其中包含的可执行文件放置在您的路径中，然后您就可以使用了。

Cargo

您还可以通过运行cargo install precious来使用cargo安装此工具。请参阅cargo文档以了解二进制将安装在哪里。

入门指南

precious 二进制文件有一个 config init 子命令，该命令会为您生成配置文件。此子命令接受以下标志

您必须传递 --auto 或至少一个 --component。在 --auto 模式下，precious 将查看您项目中的所有文件，并根据它找到的文件类型生成配置。

以下是一个 Rust 项目的示例

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

组件

以下组件被支持

• go - 为使用 golangci-lint 进行代码检查和整理的 Go 项目生成配置
• perl - 为使用各种工具（包括 perlcritic 和 perltidy）的 Perl 项目生成配置
• rust - 为使用 rustfmt 进行整理和 clippy 进行代码检查的 Rust 项目生成配置
• shell - 生成的配置使用 shfmt 进行整理和 shellcheck 进行代码检查
• gitignore - 使用 omegasort 对 .gitignore 文件进行代码检查和整理（通过排序）
• markdown - 使用 prettier 对 Markdown 文件进行代码检查和整理
• toml - 使用 taplo 对 TOML 文件进行代码检查和整理
• yaml - 使用 prettier 对 YAML 文件进行代码检查和整理

示例

此存储库的 示例目录 中有几种语言的 precious.toml 配置文件。欢迎为其他语言贡献！

示例中的配置与 precious config init 生成的配置相匹配，文件中还有更多关于如何更改此配置的详细信息。

还可以查看 示例脚本 install-dev-tools.sh，该脚本用于安装项目中所有代码检查和整理的依赖项。您可以根据需要自定义此脚本，以便仅安装项目所需的工具。

配置

Precious 通过位于项目根目录的单个 precious.toml 或 .precious.toml 文件进行配置。该文件使用 TOML 格式。

配置文件的顶层表中可以设置一个键

所有其他配置都是基于每个命令的。命令是指整理（也称为美化或格式化），代码检查，或两者兼具的操作。这些命令是外部程序，precious 将在需要时执行它们。

每个命令都在一个类似 [commands.command-name] 的块中定义。在 commands. 前缀之后的所有名称都必须是唯一的。只要每个命令都有一个唯一的名称，您就可以使用不同的命令以不同的方式运行相同的可执行文件。

命令的运行顺序与它们在配置文件中出现的顺序相同。

命令调用

有三个配置键用于命令调用。它们都是可选的。如果没有指定，precious 默认使用以下设置：

invoke      = "per-file"
working-dir = "root"
path-args   = "file"

这将在每个文件上运行一次命令，命令的工作目录为项目根目录。命令将通过将文件从根目录的相对路径作为单个参数传递给命令来传递。

invoke

invoke 键告诉 precious 如何调用命令。

还有一些针对 invoke 键的实验性选项。在未来的版本中，它们的确切名称或操作细节可能会有所变化。

它们可以写成这样

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

这些实验性选项对于优化命令的运行速度很有用。在某些情况下，命令可以以多种方式运行，而完成速度取决于需要检查或整理的文件或目录数量。

golangci-lint 工具是一个很好的例子。在几个目录上多次调用它可能比在整个存储库上调用它要快得多。然而，一旦有足够的目录进行检查，对整个存储库只调用一次将会更快。

请注意，path-args 设置需要与这些选项的两种可能情况一起工作。对于 golangci-lint，这意味着在使用 per-dir-or-once 时将其设置为 dir。

working-dir

working-dir 键告诉 precious 命令运行时的工作目录应该是什么。

工作-dir.chdir-到= "path"

working-dir的最终选项是将显式路径设置为工作目录。

使用此选项，当执行命令时，工作目录将设置为给定的子目录。传递给命令的相对路径将相对于此子目录，而不是项目根目录。

path-args

path-args键告诉precious在运行命令时如何传递路径。

不合理组合

这些配置键的大多数组合都是允许的，但也有一些不合理的组合会导致precious以错误退出。

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

如果不传递文件名，则不能为每个文件调用一次命令。

invoke = "per-dir"
path-args = "none" or "dot"
working-dir = "root"
# ... or ...
working-dir.chdir-to = "whatever"

如果不能从根目录调用一次命令而不传递目录名或文件名列表。如果您想在没有任何路径参数或使用.作为路径的情况下为每个目录运行一次命令，则必须设置working-dir = "dir"。

invoke = "once"
working-dir = "dir"

如果将工作目录设置为每个匹配目录，则不能调用一次命令。

调用示例

有关每个可能选项集的完整示例，请参阅调用示例文档。

其他每个命令的配置键

允许的每个命令的其他键如下

引用项目根目录

对于可以从子目录运行的命令，您可能需要以项目根目录的形式指定配置文件。您可以通过在cmd配置键的任何元素中使用字符串$PRECIOUS_ROOT来实现这一点。例如，您可能可以这样写

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

字符串$PRECIOUS_ROOT将被替换为项目根目录的绝对路径。

运行Precious

要获取帮助，请运行precious --help。

根命令接受以下标志

并行执行

Precious默认将始终并行执行命令，每个CPU一个进程。执行根据命令的调用配置并行化。例如，在12个CPU的系统上，具有invoke = "per-file"的命令将并行执行多达12次，每个命令执行接收一个文件。

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

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

Found config file at: /home/autarch/projects/precious/precious.toml

┌─────────────────────┬──────┬────────────────────────────────────────────────────────┐
│ Name                ┆ Type ┆ Runs                                                   │
╞═════════════════════╪══════╪════════════════════════════════════════════════════════╡
│ rustfmt             ┆ both ┆ rustfmt --edition 2021                                 │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ clippy              ┆ lint ┆ cargo clippy --locked --all-targets --all-features     │
│                     ┆      ┆ --workspace -- -D clippy::all                          │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ prettier            ┆ both ┆ ./node_modules/.bin/prettier --no-config --print-width │
│                     ┆      ┆ 100 --prose-wrap always                                │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ omegasort-gitignore ┆ both ┆ omegasort --sort path --unique                         │
└─────────────────────┴──────┴────────────────────────────────────────────────────────┘

include = "**/*.rs"
invoke = "once"
path-args = "dot" # or "none"

include     = "**/*.rs"
invoke      = "per-dir"
working-dir = "dir"
path-args   = "none"

[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]