feat: add first-class cargo-crap integration

.config/flakebox/id

@@ -1 +1 @@
-fcdbf6dfbda028e2ed526c56d98ed693ba6652d48d89785a11df463fd5d0be231b2a22937926685d82bbe5ead21be2a27bebd6ac71e019b790ba4e64c28f81ba
+38388baf24a0b3198588bd0be637b77e484d6121043ea12cbb9bdc16c6c0231676caadfd6b04a6b69258390b3403350a8e6972224a768248c3acd85e6b1a76d3

checks/cargo-crap-module.nix

@@ -0,0 +1,69 @@
+{ pkgs, mkLib }:
+let
+  inherit (pkgs) lib;
+
+  mk = config: mkLib pkgs { inherit config; };
+
+  defaultLib = mk { };
+  disabledLib = mk {
+    cargo-crap.enable = false;
+  };
+  noConfigLib = mk {
+    cargo-crap.config.enable = false;
+  };
+  preCommitLib = mk {
+    cargo-crap.pre-commit.enable = true;
+    cargo-crap.pre-commit.args = [
+      "--workspace"
+      "--threshold"
+      "123"
+      "--fail-above"
+    ];
+  };
+
+  assertMsg = lib.assertMsg;
+in
+assert assertMsg defaultLib.config.cargo-crap.enable "cargo-crap is enabled by default";
+assert assertMsg (
+  !defaultLib.config.cargo-crap.pre-commit.enable
+) "cargo-crap pre-commit is opt-in";
+assert assertMsg (builtins.hasAttr ".cargo-crap.toml" defaultLib.config.rootDir)
+  ".cargo-crap.toml is generated by default";
+assert assertMsg (builtins.hasAttr "cargo-crap" defaultLib.config.just.rules)
+  "just crap recipe is generated by default";
+assert assertMsg
+  (builtins.elem defaultLib.config.cargo-crap.package defaultLib.config.env.shellPackages)
+  "cargo-crap package is included in dev shells";
+assert assertMsg (
+  !(builtins.hasAttr "cargo_crap" defaultLib.config.git.pre-commit.hooks)
+) "cargo-crap pre-commit hook is not generated by default";
+assert assertMsg (
+  !(builtins.hasAttr ".cargo-crap.toml" disabledLib.config.rootDir)
+) "top-level disable removes generated .cargo-crap.toml";
+assert assertMsg (
+  !(builtins.hasAttr "cargo-crap" disabledLib.config.just.rules)
+) "top-level disable removes just recipe";
+assert assertMsg (
+  !(builtins.elem disabledLib.config.cargo-crap.package disabledLib.config.env.shellPackages)
+) "top-level disable removes shell package";
+assert assertMsg (
+  !(builtins.hasAttr "cargo_crap" disabledLib.config.git.pre-commit.hooks)
+) "top-level disable removes pre-commit hook";
+assert assertMsg (
+  !(builtins.hasAttr ".cargo-crap.toml" noConfigLib.config.rootDir)
+) "config disable removes only generated .cargo-crap.toml";
+assert assertMsg (builtins.hasAttr "cargo-crap" noConfigLib.config.just.rules)
+  "config disable keeps just recipe";
+assert assertMsg
+  (builtins.elem noConfigLib.config.cargo-crap.package noConfigLib.config.env.shellPackages)
+  "config disable keeps shell package";
+assert assertMsg (builtins.hasAttr "cargo_crap" preCommitLib.config.git.pre-commit.hooks)
+  "pre-commit enable generates hook";
+assert assertMsg
+  (lib.hasInfix "flakebox-in-each-cargo-workspace cargo-crap" preCommitLib.config.git.pre-commit.hooks.cargo_crap)
+  "pre-commit hook invokes cargo-crap directly";
+assert assertMsg
+  (lib.hasInfix "--threshold 123" preCommitLib.config.git.pre-commit.hooks.cargo_crap)
+  "pre-commit args are rendered into hook";
+
+pkgs.runCommand "cargo-crap-module-tests" { } "touch $out"

checks/default.nix

@@ -21,6 +21,7 @@ onlyDrvs (
       customStdenv = callPackage ./custom-stdenv { };
       nextest = callPackage ./nextest { };
       mergeArgsTests = callPackage ./mergeArgs-tests.nix { };
+      cargoCrapModule = callPackage ./cargo-crap-module.nix { inherit mkLib; };
     }
   )
 )

docs/best-practices.md

@@ -82,3 +82,33 @@ Flakebox will automatically link using `mold` on Linux, also taking care of
 some important low level NixOS details.
 
 ### TBD: `cargo` accidental-recompilation prevention
+
+## Gate high CRAP scores with cargo-crap
+
+Flakebox provides `cargo-crap` in development shells by default, generates a
+shared `.cargo-crap.toml`, and adds a `just crap` helper that runs
+`cargo-crap --workspace`.
+
+The pre-commit cargo-crap gate is intentionally opt-in because CRAP checks can be
+more expensive and project-specific than lightweight formatting or spelling
+checks. Enable it when a project has chosen suitable thresholds or coverage
+inputs:
+
+```nix
+{
+  cargo-crap.pre-commit = {
+    enable = true;
+    args = [
+      "--workspace"
+      "--threshold"
+      "100"
+      "--fail-above"
+    ];
+  };
+}
+```
+
+Customize the generated `.cargo-crap.toml` by setting
+`cargo-crap.config.content`. Disable only that generated file with
+`cargo-crap.config.enable = false`, or disable the whole cargo-crap integration
+with `cargo-crap.enable = false`.

docs/flakeboxLib.md

@@ -91,3 +91,13 @@ supported toolchains. A nested set with following keys:
 * `<toolchain>.<profile>.<output>` - e.g. `nightly.dev.workspaceDeps`, `aarch64-android.release.flakebox-tutorial` are builds using `<ci>` build profile and `<toolchain>`
 
 See [Tutorial: Flakebox in a New Project](./building-new-project.md) for more information.
+
+## `flakeboxLib.cargoCrap`
+
+`flakeboxLib.cargoCrap` exposes flakebox's packaged `cargo-crap` derivation for
+custom Nix checks and reports.
+
+Most projects should prefer the default `cargo-crap` module integration, which
+adds the tool to dev shells, generates `.cargo-crap.toml`, and provides the
+`just crap` helper. Use `flakeboxLib.cargoCrap` directly when composing custom
+crane derivations, CI report jobs, or baseline/regression gates.