treefmt.withConfig: add check function

Inspired by treefmt-nix's `config.build.check` option, add a similar
check function to `treefmt.withConfig`'s wrapper.

`check` is a function of `Path → Derivation`, which returns a derivation
that builds ok when the path is already formatted, or fails to build if
the wrapped-treefmt would change the path's formatting.

Add the `check` function, tests for it, and initial docs.

See treefmt-nix: db947814/module-options.nix (L301-L349)

(cherry picked from commit 134bfa753c)

pkgs/by-name/tr/treefmt/check-wrapper.nix

@@ -0,0 +1,50 @@
+{
+  lib,
+  gitMinimal,
+  runCommandLocal,
+  stdenv,
+  wrapper,
+}:
+/**
+  Test that the given project tree is formatted with the treefmt config.
+
+  Input argument is the path to the project tree.
+*/
+project:
+runCommandLocal "${lib.getName wrapper}-check"
+  {
+    __structuredAttrs = true;
+    strictDeps = true;
+    nativeBuildInputs = [
+      gitMinimal
+      wrapper
+    ];
+    inherit project;
+    env = {
+      LANG = if stdenv.buildPlatform.isDarwin then "en_US.UTF-8" else "C.UTF-8";
+      LC_ALL = if stdenv.buildPlatform.isDarwin then "en_US.UTF-8" else "C.UTF-8";
+    };
+    meta.description = "Check that the project tree is formatted";
+  }
+  ''
+    # Copy project files into the build-dir
+    cp -r "$project" project
+    chmod -R a+w project
+    cd project
+
+    # Setup a git repo
+    git init --initial-branch main
+    git config user.name nixbld
+    git config user.email nixbld@example.com
+    git add .
+    git commit -m init --quiet
+
+    # Run treefmt
+    treefmt --version
+    treefmt --no-cache
+
+    # Ensure nothing changed
+    git status
+    git --no-pager diff --exit-code
+    touch "$out"
+  ''

pkgs/by-name/tr/treefmt/lib.nix

@@ -40,6 +40,20 @@
   /**
     Wrap treefmt, configured using structured settings.
 
+    # Check
+
+    The resulting package has a `check` attribute of type `Path -> Derivation`.
+    The derivation returned will only build if the path supplied is already formatted correctly.
+
+    ```
+    { pkgs }:
+    let
+      myTreefmt = pkgs.treefmt.withConfig ./treefmt-config.nix;
+      project = ../.;
+    in
+    myTreefmt.check project
+    ```
+
     # Type
 
     ```

pkgs/by-name/tr/treefmt/modules/wrapper.nix

@@ -15,7 +15,7 @@
     internal = true;
   };
 
-  config.result = pkgs.symlinkJoin {
+  config.result = pkgs.symlinkJoin (finalAttrs: {
     pname = config.name;
     inherit (config.package) meta version;
     nativeBuildInputs = [ pkgs.makeBinaryWrapper ];
@@ -27,11 +27,14 @@
     passthru = {
       inherit (config) runtimeInputs;
       inherit config options;
+      check = pkgs.callPackage ../check-wrapper.nix {
+        wrapper = finalAttrs.finalPackage;
+      };
     };
     postBuild = ''
       wrapProgram "$out/bin/treefmt" \
         --prefix PATH : "$binPath" \
         --add-flags "--config-file $configFile"
     '';
-  };
+  });
 }

pkgs/by-name/tr/treefmt/tests.nix

@@ -1,6 +1,7 @@
 {
   lib,
   runCommand,
+  runCommandLocal,
   testers,
   treefmt,
   nixfmt,
@@ -31,6 +32,28 @@ let
     settings = nixfmtExampleConfig;
     runtimeInputs = [ nixfmt ];
   };
+
+  wellFormattedTree = runCommandLocal "well-formatted-project" { } ''
+    mkdir "$out"
+    cat > "$out/file.nix" <<EOF
+    {
+      foo = "bar";
+      attrs = { };
+      list = [ ];
+    }
+    EOF
+  '';
+
+  unformattedTree = runCommandLocal "unformatted-project" { } ''
+    mkdir "$out"
+    cat > "$out/file.nix" <<EOF
+    {
+      foo="bar";
+      attrs={};
+      list=[];
+    }
+    EOF
+  '';
 in
 {
   buildConfigEmpty = testEqualContents {
@@ -68,6 +91,22 @@ in
     '';
   };
 
+  nixfmtExampleCheckPasses = nixfmtExamplePackage.check wellFormattedTree;
+
+  nixfmtExampleCheckFails = testers.testBuildFailure' {
+    drv = nixfmtExamplePackage.check unformattedTree;
+    expectedBuilderExitCode = 1;
+    expectedBuilderLogEntries = [
+      "diff --git a/file.nix b/file.nix"
+      "-  foo=\"bar\";"
+      "+  foo = \"bar\";"
+      "-  attrs={};"
+      "+  attrs = { };"
+      "-  list=[];"
+      "+  list = [ ];"
+    ];
+  };
+
   runNixfmtExample =
     runCommand "run-nixfmt-example"
       {