ci(performance): add prek hook priorities for parallel execution (apache#1379)

Co-authored-by: Paul Irwin <paulirwin@gmail.com>

Author: jbampton

.pre-commit-config.yaml

@@ -16,28 +16,50 @@
 # under the License.
 
 ---
-# https://pre-commit.com/#installation
+# prek-style priority keys enables prek to run independent hooks in parallel, improving pre-commit check times.
+# The priority values are assigned to structure the hook execution into logical stages, ensuring correct ordering of
+# file modifications and maximum concurrency of read-only checks.
+
+# Priority Levels: Hooks can be assigned different priority numbers. Hooks with a priority of 0 (or a higher numerical
+# value, depending on configuration) run first or alongside other zero-priority hooks to decrease total end-to-end
+# execution time.
+
+# Priority Groups and Ordering Design
+
+# | Stage / Priority | Hooks | Rationale |
+# |---|---|---|
+# | **Priority 10** | `identity`, `check-hooks-apply` | **Meta & Setup**: Ensure environment is valid before executing heavy checks. |
+# | **Priority 20** | `fix-byte-order-marker` | **File Cleanups (Broad)**: Fix BOM first so subsequent steps work with clean UTF-8 text. |
+# | **Priority 30** | `trailing-whitespace` | **Formatting (Broad)**: Cleans up whitespace on files before other hooks validate them. |
+# | **Priority 40** | `doctoc`, `oxipng`, `file-contents-sorter` | **Disjoint Modifiers**: These modify different sets of files (`README.md`, `.png` files, and `codespell.txt` respectively). Running them concurrently is safe. |
+# | **Priority 50** | `codespell`, `check-ast`, `check-builtin-literals`, `check-case-conflict`, `check-executables-have-shebangs`, `check-illegal-windows-names`, `check-json`, `check-merge-conflict`, `check-vcs-permalinks`, `check-xml`, `check-yaml`, `debug-statements`, `detect-aws-credentials`, `detect-private-key`, `forbid-submodules`, `gitleaks`, `bandit`|
+# |                 | **Read-Only / Syntax / Security**: The bulk of the suite. These hooks only read and validate files without modifying them, allowing full parallel execution. |
+
+# https://prek.j178.dev/installation/
 default_stages: [pre-commit, pre-push]
 default_language_version:
   # force all unspecified Python hooks to run python3
   python: python3
-minimum_pre_commit_version: '3.2.0'
+minimum_prek_version: '0.3.4'
 repos:
   - repo: meta
     hooks:
       - id: identity
         name: run identity check
         description: check you have set your git identity
+        priority: 10
       - id: check-hooks-apply
         name: run check hooks apply
         description: check that all the hooks apply to the repository
+        priority: 10
   - repo: https://github.com/thlorenz/doctoc.git
     rev: 59dcae910a6ad4bbe8711275b854e3cd5c30f08b # frozen: v2.5.0
     hooks:
       - id: doctoc
         name: add TOC for Markdown files
         description: automatically keeps your table of contents up to date
         files: ^README\.md$
+        priority: 40
   - repo: https://github.com/codespell-project/codespell
     rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a # frozen: v2.4.2
     hooks:
@@ -46,13 +68,15 @@ repos:
         description: check spelling with codespell
         exclude: ^src/Lucene\.Net\.Analysis\.Common/Analysis/../.*\.rslp$|^.*Lucene\.Net\.Tests.*$
         args: [--ignore-words=.github/linters/codespell.txt]
+        priority: 50
   - repo: https://github.com/oxipng/oxipng
     rev: 628e241e23f368097883807fa6e985ccf7c00357 # frozen: v10.1.1
     hooks:
       - id: oxipng
         name: run oxipng
         description: check PNG files with oxipng
         args: [ '--fix', '-o', '4', '--strip', 'safe', '--alpha' ]
+        priority: 40
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # frozen: v6.0.0
     hooks:
@@ -61,63 +85,81 @@ repos:
         description: trims trailing whitespace
         files: \.(bat|config|json|md|props|ps1|rdf|targets|tmpl|xml|ya?ml)$
         args: [--markdown-linebreak-ext=md]
+        priority: 30
       - id: check-ast
         name: run check-ast
         description: check Python files for syntax errors
+        priority: 50
       - id: check-builtin-literals
         name: run check-builtin-literals
         description: check Python files for proper use of built-in literals
+        priority: 50
       - id: check-case-conflict
         name: run check-case-conflict
         description: check for case conflicts in file names
+        priority: 50
       - id: check-executables-have-shebangs
         name: run check-executables-have-shebangs
         description: check that executable scripts have shebang lines
+        priority: 50
       - id: check-illegal-windows-names
         name: run check-illegal-windows-names
         description: check for Windows-illegal file names
+        priority: 50
       - id: check-json
         name: run check-json
         description: check JSON files for syntax errors
+        priority: 50
       - id: check-merge-conflict
         name: run check-merge-conflict
         description: check for merge conflict markers
+        priority: 50
       - id: check-vcs-permalinks
         name: run check-vcs-permalinks
         description: ensures that links to vcs websites are permalinks
+        priority: 50
       - id: check-xml
         name: run check-xml
         description: attempts to load all xml files to verify syntax
+        priority: 50
       - id: check-yaml
         name: run check-yaml
         description: attempts to load all yaml files to verify syntax
+        priority: 50
       - id: debug-statements
         name: run debug-statements
         description: check for debugger imports and py37+ `breakpoint()` calls in python source.
+        priority: 50
       - id: detect-aws-credentials
         name: run detect-aws-credentials
         description: checks for the existence of AWS secrets that you have set up with the AWS CLI
         args: [--allow-missing-credentials]
+        priority: 50
       - id: detect-private-key
         name: run detect-private-key
         description: checks for the existence of private keys
+        priority: 50
       - id: file-contents-sorter
         name: run file-contents-sorter
         description: sort the lines in specified files (defaults to alphabetical)
         args: [--unique]
         files: ^\.github/linters/codespell\.txt$
+        priority: 40
       - id: forbid-submodules
         name: run forbid-submodules
         description: forbids any submodules in the repository
+        priority: 50
       - id: fix-byte-order-marker
         name: run fix-byte-order-marker
         description: fixes files with UTF-8 byte order markers
+        priority: 20
   - repo: https://github.com/gitleaks/gitleaks
     rev: 83d9cd684c87d95d656c1458ef04895a7f1cbd8e # frozen: v8.30.1
     hooks:
       - id: gitleaks
         name: run gitleaks
         description: check for secrets with gitleaks
+        priority: 50
   - repo: https://github.com/PyCQA/bandit
     rev: 92ae8b82fb422a639f0ed8d99e96cea769594e08 # frozen: 1.9.4
     hooks:
@@ -126,6 +168,7 @@ repos:
         description: check Python code for security issues
         args: ['-c=pyproject.toml']
         additional_dependencies: ['bandit[toml]']
+        priority: 50
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: a4d5d37e66ebcd6b3705204a1d6dbb56dea66338 # frozen: v0.49.0
     hooks:
@@ -136,3 +179,4 @@ repos:
         exclude: ^\.github/.*$
         types: [markdown]
         files: \.md$
+        priority: 50