feat(pre-commits): Default hooks to run during pre-commit only

nix/general/devshell.nix

@@ -32,6 +32,13 @@ importingFlake: {
             package = config.prek-pre-commit.package.wrapper;
           }
 
+          {
+            name = "prek --stage pre-push";
+            help = "*Also* slow pre-commit hooks";
+            category = "[[lints and checks]]";
+            package = config.prek-pre-commit.package.wrapper;
+          }
+
           {
             name = "prek -s main -o HEAD";
             help = "Run pre-commit hooks on all commits in the current branch";

nix/general/workflows/check-pre-commit-hooks.nix

@@ -38,8 +38,9 @@ in
         {
           name = "Run pre-commit hooks";
           shell = "nix develop .#standards --command bash {0}";
-          run = "prek --all-files --show-diff-on-failure";
+          run = "prek --all-files --show-diff-on-failure --stage pre-push";
           env = {
+            PREK_COLOR = "always";
             # On some CI runners, the cache would time out, causing the pipeline to fail.
             # Since the official documentation (https://treefmt.com/usage/#ci-integration)
             # recommends using `----no-cache` anyway, we add it here.

nix/modules/prek-pre-commit.nix

@@ -27,14 +27,78 @@ in
           description = ''
             `prek` configuration for each workspace.
 
+            Any hooks defined *must* run either under the `pre-commit` or `pre-push`
+            stage to be picked up by CI.
+
+            `pre-push` hooks are intended to be used for heavier work that we don't
+            want to run on every commit (so that rebases stay spiffy).
+
             Note that any hooks that depend on system packages being installed
             should have their packages installed via the
             `prek-pre-commit.package.runtimePkgs` option.
 
             See the [`prek` documentation](https://prek.j178.dev/workspace/) for details.
           '';
           default = { };
-          type = types.attrsOf (types.submodule { freeformType = settingsFormat.type; });
+          type = types.attrsOf (
+            types.submodule {
+              freeformType = settingsFormat.type;
+
+              options.repos = lib.mkOption {
+                description = ''
+                  The prek `repos` to configure.
+
+                  See https://prek.j178.dev/reference/configuration/#repos-required
+                '';
+
+                type = lib.types.listOf (
+                  lib.types.submodule {
+                    freeformType = settingsFormat.type;
+
+                    options.hooks = lib.mkOption {
+                      description = ''
+                        The prek `hooks` to configure for this repo.
+
+                        See https://prek.j178.dev/reference/configuration/#hook-entries
+                      '';
+                      default = [ ];
+
+                      type = lib.types.listOf (
+                        lib.types.submodule {
+                          freeformType = settingsFormat.type;
+
+                          options.stages = lib.mkOption {
+                            description = ''
+                              The stages during which to run this pre-commit.
+
+                              Only `pre-push` is currently supported.
+                            '';
+                            default = [ ];
+                            apply =
+                              stages:
+                              if stages != [ ] && stages != [ "pre-push" ] then
+                                builtins.abort ''
+                                  Invalid hook stages.
+
+                                  Currently, only pre-push hooks are allowed. To make CI scripting easier,
+                                  we're forcing all other hooks to be defined as running under all stages.
+
+                                  If you want to use a different stage, or want to explicitly run a specific
+                                  hook only during pre-commit, talk to the engineering-standards maintainers.
+
+                                ''
+                              else
+                                [ ];
+                          };
+                        }
+                      );
+                    };
+                  }
+                );
+                default = [ ];
+              };
+            }
+          );
         };
       };
     }