Add prek util list-builtins command

[ichoosetoaccept]

Fix misleading prek list help text and add prek list-builtins command

Summary

prek list says "List available hooks" but actually lists hooks configured in the current project. This PR fixes the wording and adds a new list-builtins command so users can discover all built-in hooks from the CLI.

Motivation

The list subcommand's help text reads:

$ prek list -h
List available hooks

This is misleading. prek list does not list hooks that are available to use — it lists hooks that are currently configured in the project's .pre-commit-config.yaml. "Available" implies a catalog of all possible hooks (especially builtins), when the actual behavior is scoped to the current config.

How this causes confusion

1. User runs prek list in Project A, which has a local hook named no-commit-to-main
2. Output shows .:no-commit-to-main — reads like an "available" hook
3. User uses id: no-commit-to-main under repo: builtin in Project B
4. prek run fails: unknown builtin hook id "no-commit-to-main"

The user reasonably assumed prek list was showing hooks they could use anywhere, because the help text says "available."

After this PR

$ prek -h
  list               List hooks configured in the current project
  list-builtins      List all built-in hooks bundled with prek

$ prek list-builtins
check-added-large-files
check-case-conflict
check-executables-have-shebangs
check-json
check-json5
check-merge-conflict
check-symlinks
check-toml
check-xml
check-yaml
detect-private-key
end-of-file-fixer
fix-byte-order-marker
mixed-line-ending
no-commit-to-branch
trailing-whitespace

Verbose mode shows descriptions:

$ prek list-builtins -v
check-added-large-files
  prevents giant files from being committed.

check-case-conflict
  checks for files that would conflict in case-insensitive filesystems
...

JSON output is also supported via --output-format=json.

What changed

crates/prek/src/cli/mod.rs

• Fixed List doc comment from "List available hooks" to "List hooks configured in the current project"
• Added ListBuiltins(ListBuiltinsArgs) command variant with --output-format option

crates/prek/src/cli/list_builtins.rs (new)

• Iterates all BuiltinHooks variants via strum::EnumIter and outputs their ID, name, and description
• Supports text (default), verbose, and JSON output formats
• Works from any directory — no config file or git repo required

crates/prek/src/hooks/builtin_hooks/mod.rs

• Added strum::EnumIter derive to BuiltinHooks enum

crates/prek/src/main.rs

• Wired up Command::ListBuiltins dispatch

crates/prek/tests/list_builtins.rs (new)

• list_builtins_basic: verifies plain text output lists all 16 builtin hook IDs
• list_builtins_verbose: verifies verbose output includes descriptions
• list_builtins_json: verifies JSON output structure

docs/cli.md

• Auto-regenerated to include the new list-builtins command

Closes #1599

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.68%. Comparing base (b4ed3ee) to head (08a2e4c).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1600      +/-   ##
==========================================
+ Coverage   91.67%   91.68%   +0.01%     
==========================================
  Files          93       94       +1     
  Lines       18333    18366      +33     
==========================================
+ Hits        16806    16839      +33     
  Misses       1527     1527              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[prek-ci-bot]

📦 Cargo Bloat Comparison

Binary size change: +0.00% (23.7 MiB → 23.7 MiB)

Expand for cargo-bloat output

Head Branch Results

 File  .text    Size             Crate Name
 0.3%   0.8% 85.0KiB             prek? <prek::cli::Command as clap_builder::derive::Subcommand>::augment_subcommands
 0.3%   0.7% 70.4KiB              prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.3%   0.6% 65.6KiB              prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.2%   0.5% 51.2KiB annotate_snippets annotate_snippets::renderer::render::render
 0.2%   0.5% 50.5KiB              prek prek::languages::<impl prek::config::Language>::install::{{closure}}
 0.2%   0.4% 43.4KiB              prek prek::identify::by_extension::{{closure}}
 0.2%   0.4% 41.5KiB              prek prek::cli::run::run::run::{{closure}}
 0.2%   0.4% 39.5KiB              prek prek::run::{{closure}}
 0.1%   0.3% 32.0KiB             prek? <prek::cli::RunArgs as clap_builder::derive::Args>::augment_args
 0.1%   0.3% 28.4KiB      serde_saphyr saphyr_parser_bw::scanner::Scanner<T>::fetch_more_tokens
 0.1%   0.2% 24.8KiB             prek? <prek::config::_::<impl serde_core::de::Deserialize for prek::config::Config>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map
 0.1%   0.2% 22.6KiB      serde_saphyr saphyr_parser_bw::scanner::Scanner<T>::fetch_more_tokens
 0.1%   0.2% 22.2KiB              prek prek::hooks::meta_hooks::MetaHooks::run::{{closure}}
 0.1%   0.2% 21.1KiB      clap_builder clap_builder::parser::parser::Parser::get_matches_with
 0.1%   0.2% 20.4KiB              prek prek::hooks::meta_hooks::MetaHooks::run::{{closure}}
 0.1%   0.2% 20.0KiB   cargo_metadata? <cargo_metadata::_::<impl serde_core::de::Deserialize for cargo_metadata::Package>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map
 0.1%   0.2% 19.9KiB              prek prek::archive::unzip::{{closure}}
 0.1%   0.2% 19.6KiB              prek prek::cli::run::filter::collect_files_from_args::{{closure}}
 0.1%   0.2% 19.3KiB               std core::ptr::drop_in_place<prek::languages::<impl prek::config::Language>::install::{{closure}}>
 0.1%   0.2% 19.2KiB              prek <prek::languages::ruby::ruby::Ruby as prek::languages::LanguageImpl>::install::{{closure}}
38.4%  91.4%  9.1MiB                   And 20876 smaller methods. Use -n N to show more.
42.0% 100.0% 10.0MiB                   .text section size, the file size is 23.7MiB

Base Branch Results

 File  .text    Size             Crate Name
 0.3%   0.8% 78.2KiB             prek? <prek::cli::Command as clap_builder::derive::Subcommand>::augment_subcommands
 0.3%   0.7% 70.4KiB              prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.3%   0.6% 65.6KiB              prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.2%   0.5% 51.2KiB annotate_snippets annotate_snippets::renderer::render::render
 0.2%   0.5% 50.5KiB              prek prek::languages::<impl prek::config::Language>::install::{{closure}}
 0.2%   0.4% 43.4KiB              prek prek::identify::by_extension::{{closure}}
 0.2%   0.4% 41.1KiB              prek prek::cli::run::run::run::{{closure}}
 0.2%   0.4% 38.6KiB              prek prek::run::{{closure}}
 0.1%   0.3% 32.0KiB             prek? <prek::cli::RunArgs as clap_builder::derive::Args>::augment_args
 0.1%   0.3% 28.4KiB      serde_saphyr saphyr_parser_bw::scanner::Scanner<T>::fetch_more_tokens
 0.1%   0.2% 24.8KiB             prek? <prek::config::_::<impl serde_core::de::Deserialize for prek::config::Config>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map
 0.1%   0.2% 22.6KiB      serde_saphyr saphyr_parser_bw::scanner::Scanner<T>::fetch_more_tokens
 0.1%   0.2% 22.2KiB              prek prek::hooks::meta_hooks::MetaHooks::run::{{closure}}
 0.1%   0.2% 22.2KiB              prek prek::hooks::meta_hooks::MetaHooks::run::{{closure}}
 0.1%   0.2% 21.1KiB      clap_builder clap_builder::parser::parser::Parser::get_matches_with
 0.1%   0.2% 20.0KiB   cargo_metadata? <cargo_metadata::_::<impl serde_core::de::Deserialize for cargo_metadata::Package>::deserialize::__Visitor as serde_core::de::Visitor>::visit_map
 0.1%   0.2% 19.8KiB              prek prek::archive::unzip::{{closure}}
 0.1%   0.2% 19.6KiB              prek prek::cli::run::filter::collect_files_from_args::{{closure}}
 0.1%   0.2% 19.3KiB               std core::ptr::drop_in_place<prek::languages::<impl prek::config::Language>::install::{{closure}}>
 0.1%   0.2% 19.3KiB     serde_saphyr? <serde_saphyr::de::YamlDeserializer as serde_core::de::Deserializer>::deserialize_any
38.4%  91.5%  9.1MiB                   And 20951 smaller methods. Use -n N to show more.
42.0% 100.0% 10.0MiB                   .text section size, the file size is 23.7MiB

[j178]

Thanks!