Add check-shebang-scripts-are-executable builtin hook

[j178]

Closes #1834

[codecov]

Codecov Report

❌ Patch coverage is 93.56725% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.94%. Comparing base (cb3f71c) to head (e3531a6).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
...re_commit_hooks/check_executables_have_shebangs.rs	86.66%	4 Missing ⚠️
...mmit_hooks/check_shebang_scripts_are_executable.rs	90.90%	4 Missing ⚠️
crates/prek/src/hooks/pre_commit_hooks/shebangs.rs	97.50%	2 Missing ⚠️
crates/prek/src/hooks/pre_commit_hooks/mod.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1847      +/-   ##
==========================================
+ Coverage   91.85%   91.94%   +0.08%     
==========================================
  Files         103      106       +3     
  Lines       20788    20994     +206     
==========================================
+ Hits        19095    19303     +208     
+ Misses       1693     1691       -2     

☔ 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.

[Copilot]

Pull request overview

Adds support for the check-shebang-scripts-are-executable hook across the Rust implementation, builtin registration, and user-facing surfaces (docs + schema), along with tests to validate behavior and listing output.

Changes:

• Implement check-shebang-scripts-are-executable (including shared shebang/git-index helpers) and wire it into the pre-commit-hooks fast-path and builtin hooks registry.
• Extend integration tests and builtin hook listings to include the new hook.
• Update documentation and JSON schema to expose the new hook id.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
prek.schema.json	Adds the new hook id to the schema’s allowed hook list.
docs/builtin.md	Documents the new builtin hook and adds it to supported hook lists.
crates/prek/tests/list_builtins.rs	Updates builtin listing snapshots (plain/verbose/json) to include the new hook.
crates/prek/tests/builtin_hooks.rs	Adds an end-to-end test covering failure + success cases for the new builtin hook.
crates/prek/src/hooks/pre_commit_hooks/shebangs.rs	Introduces shared utilities for shebang detection and parsing git index --stage output.
crates/prek/src/hooks/pre_commit_hooks/mod.rs	Registers the new hook module and adds it to the PreCommitHooks dispatcher.
crates/prek/src/hooks/pre_commit_hooks/check_shebang_scripts_are_executable.rs	Implements the hook logic and its warning message formatting.
crates/prek/src/hooks/pre_commit_hooks/check_executables_have_shebangs.rs	Refactors to reuse the new shared shebang/git-index utilities and message builder.
crates/prek/src/hooks/builtin_hooks/mod.rs	Registers the hook as repo: builtin with metadata (name/description/types/stages).

[prek-ci-bot]

📦 Cargo Bloat Comparison

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

Expand for cargo-bloat output

Head Branch Results

 File  .text     Size             Crate Name
 1.3%   2.7% 332.0KiB        aws_lc_sys aws_lc_0_39_0_aes_gcm_encrypt_avx512
 1.3%   2.7% 332.0KiB        aws_lc_sys aws_lc_0_39_0_aes_gcm_decrypt_avx512
 0.3%   0.6%  80.0KiB              prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.3%   0.6%  72.2KiB              prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.3%   0.6%  69.3KiB             prek? <prek::cli::Command as clap_builder::derive::Subcommand>::augment_subcommands
 0.2%   0.5%  56.8KiB              prek prek::languages::<impl prek::config::Language>::install::{{closure}}
 0.2%   0.4%  51.0KiB annotate_snippets annotate_snippets::renderer::render::render
 0.2%   0.4%  46.0KiB              prek prek::run::{{closure}}
 0.2%   0.3%  41.8KiB              prek prek::cli::run::run::run::{{closure}}
 0.1%   0.3%  32.0KiB             prek? <prek::cli::RunArgs as clap_builder::derive::Args>::augment_args
 0.1%   0.2%  28.0KiB        aws_lc_sys aws_lc_0_39_0_edwards25519_scalarmuldouble_alt
 0.1%   0.2%  27.8KiB      serde_saphyr saphyr_parser_bw::scanner::Scanner<T>::fetch_more_tokens
 0.1%   0.2%  27.5KiB        aws_lc_sys aws_lc_0_39_0_edwards25519_scalarmuldouble
 0.1%   0.2%  26.6KiB             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%  25.9KiB              prek prek::cli::try_repo::try_repo::{{closure}}
 0.1%   0.2%  24.2KiB               std core::ptr::drop_in_place<prek::languages::<impl prek::config::Language>::install::{{closure}}>
 0.1%   0.2%  23.0KiB              prek prek::hooks::meta_hooks::MetaHooks::run::{{closure}}
 0.1%   0.2%  22.4KiB      serde_saphyr saphyr_parser_bw::scanner::Scanner<T>::fetch_more_tokens
 0.1%   0.2%  22.3KiB         [Unknown] Lp384_montjscalarmul_alt_p384_montjadd
 0.1%   0.2%  21.7KiB              prek prek::workspace::Project::init_hooks::{{closure}}
41.3%  86.1%  10.4MiB                   And 23709 smaller methods. Use -n N to show more.
48.0% 100.0%  12.1MiB                   .text section size, the file size is 25.1MiB

Base Branch Results

 File  .text     Size             Crate Name
 1.3%   2.7% 332.0KiB        aws_lc_sys aws_lc_0_39_0_aes_gcm_encrypt_avx512
 1.3%   2.7% 332.0KiB        aws_lc_sys aws_lc_0_39_0_aes_gcm_decrypt_avx512
 0.3%   0.7%  82.7KiB             prek? <prek::cli::Command as clap_builder::derive::Subcommand>::augment_subcommands
 0.3%   0.7%  81.1KiB              prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.3%   0.6%  74.1KiB              prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.2%   0.5%  56.9KiB              prek prek::languages::<impl prek::config::Language>::install::{{closure}}
 0.2%   0.4%  51.0KiB annotate_snippets annotate_snippets::renderer::render::render
 0.2%   0.4%  47.1KiB              prek prek::run::{{closure}}
 0.2%   0.3%  41.8KiB              prek prek::cli::run::run::run::{{closure}}
 0.1%   0.3%  32.0KiB             prek? <prek::cli::RunArgs as clap_builder::derive::Args>::augment_args
 0.1%   0.2%  28.0KiB        aws_lc_sys aws_lc_0_39_0_edwards25519_scalarmuldouble_alt
 0.1%   0.2%  27.8KiB      serde_saphyr saphyr_parser_bw::scanner::Scanner<T>::fetch_more_tokens
 0.1%   0.2%  27.5KiB        aws_lc_sys aws_lc_0_39_0_edwards25519_scalarmuldouble
 0.1%   0.2%  26.2KiB              prek prek::cli::try_repo::try_repo::{{closure}}
 0.1%   0.2%  25.4KiB             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%  24.4KiB               std core::ptr::drop_in_place<prek::languages::<impl prek::config::Language>::install::{{closure}}>
 0.1%   0.2%  23.0KiB              prek prek::hooks::meta_hooks::MetaHooks::run::{{closure}}
 0.1%   0.2%  22.4KiB      serde_saphyr saphyr_parser_bw::scanner::Scanner<T>::fetch_more_tokens
 0.1%   0.2%  22.3KiB         [Unknown] Lp384_montjscalarmul_alt_p384_montjadd
 0.1%   0.2%  21.6KiB              prek prek::workspace::Project::init_hooks::{{closure}}
41.2%  85.9%  10.3MiB                   And 23547 smaller methods. Use -n N to show more.
48.0% 100.0%  12.0MiB                   .text section size, the file size is 25.1MiB

[prek-ci-bot]

⚡️ Hyperfine Benchmarks

Summary: 0 regressions, 0 improvements above the 10% threshold.

Environment

• OS: Linux 6.14.0-1017-azure
• CPU: 4 cores
• prek version: prek 0.3.6+27 (ff41995 2026-03-22)
• Rust version: rustc 1.94.0 (4a4ef493e 2026-03-02)
• Hyperfine version: hyperfine 1.20.0

CLI Commands

Benchmarking basic commands in the main repo:

prek --version

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base --version	2.4 ± 0.1	2.3	2.8	1.00
prek-head --version	2.4 ± 0.1	2.2	2.9	1.03 ± 0.06

prek list

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base list	10.2 ± 0.8	9.4	13.6	1.04 ± 0.12
prek-head list	9.8 ± 0.8	9.1	14.8	1.00

prek validate-config .pre-commit-config.yaml

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base validate-config .pre-commit-config.yaml	3.3 ± 0.1	3.2	3.5	1.00
prek-head validate-config .pre-commit-config.yaml	3.3 ± 0.1	3.2	3.7	1.00 ± 0.03

prek sample-config

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base sample-config	2.7 ± 0.1	2.6	2.8	1.00
prek-head sample-config	2.8 ± 0.6	2.6	6.7	1.04 ± 0.22

Cold vs Warm Runs

Comparing first run (cold) vs subsequent runs (warm cache):

prek run --all-files (cold - no cache)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run --all-files	164.1 ± 3.7	159.5	170.3	1.00
prek-head run --all-files	167.4 ± 4.6	161.5	173.3	1.02 ± 0.04

prek run --all-files (warm - with cache)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run --all-files	165.2 ± 3.7	159.2	173.1	1.00
prek-head run --all-files	165.8 ± 5.4	158.7	180.3	1.00 ± 0.04

Full Hook Suite

Running the builtin hook suite on the benchmark workspace:

prek run --all-files (full builtin hook suite)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run --all-files	165.9 ± 4.5	159.1	175.8	1.00
prek-head run --all-files	171.8 ± 35.6	156.8	414.1	1.04 ± 0.22

Individual Hook Performance

Benchmarking each hook individually on the test repo:

prek run trailing-whitespace --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run trailing-whitespace --all-files	23.2 ± 1.2	22.4	29.1	1.00
prek-head run trailing-whitespace --all-files	23.3 ± 0.6	22.2	24.6	1.00 ± 0.06

prek run end-of-file-fixer --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run end-of-file-fixer --all-files	31.7 ± 2.5	27.5	37.4	1.00
prek-head run end-of-file-fixer --all-files	31.7 ± 2.6	27.5	39.2	1.00 ± 0.11

prek run check-json --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-json --all-files	14.0 ± 0.5	13.3	15.7	1.07 ± 0.05
prek-head run check-json --all-files	13.1 ± 0.3	12.5	13.7	1.00

prek run check-yaml --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-yaml --all-files	13.0 ± 0.5	12.3	14.6	1.00
prek-head run check-yaml --all-files	13.4 ± 1.1	12.6	17.6	1.02 ± 0.09

prek run check-toml --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-toml --all-files	13.7 ± 1.4	12.4	19.1	1.07 ± 0.11
prek-head run check-toml --all-files	12.8 ± 0.4	12.2	14.0	1.00

prek run check-xml --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-xml --all-files	13.9 ± 1.9	12.5	22.4	1.04 ± 0.18
prek-head run check-xml --all-files	13.3 ± 1.5	12.4	20.7	1.00

prek run detect-private-key --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run detect-private-key --all-files	20.6 ± 1.7	17.8	24.3	1.01 ± 0.14
prek-head run detect-private-key --all-files	20.3 ± 2.2	17.7	27.8	1.00

prek run fix-byte-order-marker --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run fix-byte-order-marker --all-files	26.5 ± 1.8	23.4	31.7	1.00
prek-head run fix-byte-order-marker --all-files	26.9 ± 2.0	22.5	30.2	1.01 ± 0.10

Installation Performance

Benchmarking hook installation (fast path hooks skip Python setup):

prek install-hooks (cold - no cache)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base install-hooks	5.2 ± 0.1	5.1	5.4	1.00
prek-head install-hooks	5.3 ± 0.2	5.1	5.5	1.02 ± 0.04

prek install-hooks (warm - with cache)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base install-hooks	5.2 ± 0.0	5.1	5.2	1.00
prek-head install-hooks	5.2 ± 0.1	5.1	5.4	1.01 ± 0.03

File Filtering/Scoping Performance

Testing different file selection modes:

prek run (staged files only)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run	57.1 ± 3.1	53.9	67.9	1.00
prek-head run	57.3 ± 3.1	53.7	65.1	1.00 ± 0.08

prek run --files '*.json' (specific file type)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run --files '*.json'	10.1 ± 0.4	9.7	11.1	1.00
prek-head run --files '*.json'	10.3 ± 1.4	9.6	15.8	1.02 ± 0.14

Workspace Discovery & Initialization

Benchmarking hook discovery and initialization overhead:

prek run --dry-run --all-files (measures init overhead)

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run --dry-run --all-files	16.0 ± 1.4	14.6	18.7	1.07 ± 0.10
prek-head run --dry-run --all-files	14.9 ± 0.4	14.3	16.4	1.00

Meta Hooks Performance

Benchmarking meta hooks separately:

prek run check-hooks-apply --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-hooks-apply --all-files	15.4 ± 1.2	13.5	18.1	1.15 ± 0.09
prek-head run check-hooks-apply --all-files	13.4 ± 0.3	13.0	14.0	1.00

prek run check-useless-excludes --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run check-useless-excludes --all-files	13.6 ± 0.9	12.8	16.3	1.00
prek-head run check-useless-excludes --all-files	14.9 ± 3.3	13.1	24.9	1.09 ± 0.25

prek run identity --all-files

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
prek-base run identity --all-files	11.8 ± 0.2	11.5	12.1	1.00
prek-head run identity --all-files	11.8 ± 0.4	11.4	12.8	1.00 ± 0.03