testers.lycheeLinkCheck: init

doc/build-helpers/testers.chapter.md

@@ -36,6 +36,45 @@ passthru.tests.pkg-config = testers.hasPkgConfigModules {
 
 :::
 
+## `lycheeLinkCheck` {#tester-lycheeLinkCheck}
+
+Check that internal hyperlinks are correct, using the [`lychee` package](https://search.nixos.org/packages?show=lychee&type=packages&query=lychee).
+
+Only an offline check is performed, so that network access is not required.
+
+:::{.example #ex-lycheelinkcheck}
+
+# Check hyperlinks in the `nix` documentation
+
+```nix
+testers.lycheeLinkCheck {
+  site = nix.doc + "/share/doc/nix/manual";
+}
+```
+
+:::
+
+### Parameters {#tester-lycheeLinkCheck-params}
+
+#### `site` (required) {#tester-lycheeLinkCheck-param-site}
+
+The path to the files to check.
+
+#### `extraConfig` (optional) {#tester-lycheeLinkCheck-param-extraConfig}
+
+Extra configuration to pass to `lychee` in its [config file](https://github.com/lycheeverse/lychee/blob/master/lychee.example.toml). It is automatically [translated](https://nixos.org/manual/nixos/stable/index.html#sec-settings-nix-representable) to TOML.
+
+Example: `{ "include_verbatim" = true; }`
+
+#### `lychee` (optional) {#tester-lycheeLinkCheck-param-lychee}
+
+The `lychee` package to use.
+
+#### `remapUrl` (optional) {#tester-lycheeLinkCheck-param-remapUrl}
+
+A URL to which the files may be deployed.
+Instead of ignoring this URL because the check is offline, `lychee` will check that the links to this URL are correct, by pretending `site` is deployed there.
+
 ## `testVersion` {#tester-testVersion}
 
 Checks that the output from running a command contains the specified version string in it as a whole word.

pkgs/build-support/testers/default.nix

@@ -1,6 +1,10 @@
 { pkgs, pkgsLinux, buildPackages, lib, callPackage, runCommand, stdenv, substituteAll, testers }:
 # Documentation is in doc/builders/testers.chapter.md
 {
+  # See https://nixos.org/manual/nixpkgs/unstable/#tester-lycheeLinkCheck
+  # or doc/builders/testers.chapter.md
+  inherit (callPackage ./lychee.nix {}) lycheeLinkCheck;
+
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailure
   # or doc/builders/testers.chapter.md
   testBuildFailure = drv: drv.overrideAttrs (orig: {

pkgs/build-support/testers/lychee.nix

@@ -0,0 +1,37 @@
+deps@{ formats, lib, lychee, stdenv }:
+let
+
+  # See https://nixos.org/manual/nixpkgs/unstable/#tester-lycheeLinkCheck
+  # or doc/builders/testers.chapter.md
+  lycheeLinkCheck = {
+    site,
+    remapUrl ? null,
+    lychee ? deps.lychee,
+    extraConfig ? { },
+  }:
+    stdenv.mkDerivation (finalAttrs: {
+      name = "lychee-link-check";
+      inherit site;
+      nativeBuildInputs = [ finalAttrs.passthru.lychee ];
+      configFile = (formats.toml {}).generate "lychee.toml" finalAttrs.passthru.config;
+
+      # These can be overriden with overrideAttrs if needed.
+      passthru = {
+        inherit lychee remapUrl;
+        config = {
+          include_fragments = true;
+        } // lib.optionalAttrs (finalAttrs.passthru.remapUrl != null) {
+          remap = [ "${remapUrl} file://${finalAttrs.site}" ];
+        } // extraConfig;
+      };
+      buildCommand = ''
+        echo Checking internal links on $site
+        lychee --offline --config $configFile $site
+        touch $out
+      '';
+    });
+
+in
+{
+  inherit lycheeLinkCheck;
+}

pkgs/build-support/testers/test/default.nix

@@ -12,6 +12,8 @@ let
 
 in
 lib.recurseIntoAttrs {
+  lycheeLinkCheck = lib.recurseIntoAttrs pkgs.lychee.tests;
+
   hasPkgConfigModules = pkgs.callPackage ../hasPkgConfigModules/tests.nix { };
 
   runNixOSTest-example = pkgs-with-overlay.testers.runNixOSTest ({ lib, ... }: {

pkgs/tools/networking/lychee/default.nix

@@ -1,4 +1,5 @@
-{ lib
+{ callPackage
+, lib
 , stdenv
 , rustPlatform
 , fetchFromGitHub
@@ -41,6 +42,13 @@ rustPlatform.buildRustPackage rec {
     "--skip=src/lib.rs"
   ];
 
+  passthru.tests = {
+    # NOTE: These assume that testers.lycheeLinkCheck uses this exact derivation.
+    #       Which is true most of the time, but not necessarily after overriding.
+    ok = callPackage ./tests/ok.nix { };
+    fail = callPackage ./tests/fail.nix { };
+  };
+
   meta = with lib; {
     description = "A fast, async, stream-based link checker written in Rust";
     homepage = "https://github.com/lycheeverse/lychee";

pkgs/tools/networking/lychee/tests/fail.nix

@@ -0,0 +1,21 @@
+{ runCommand, testers }:
+let
+  sitePkg = runCommand "site" { } ''
+    dist=$out/dist
+    mkdir -p $dist
+    echo "<html><body><a href=\"https://example.com/foo.html#butwhere\">foo</a></body></html>" > $dist/index.html
+    echo "<html><body><a href=\".\">index</a></body></html>" > $dist/foo.html
+  '';
+
+  linkCheck = testers.lycheeLinkCheck {
+    site = sitePkg + "/dist";
+    remapUrl = "https://example.com";
+  };
+
+  failure = testers.testBuildFailure linkCheck;
+
+in
+  runCommand "link-check-fail" { inherit failure; } ''
+    grep -F butwhere $failure/testBuildFailure.log >/dev/null
+    touch $out
+  ''

pkgs/tools/networking/lychee/tests/ok.nix

@@ -0,0 +1,12 @@
+{ runCommand, testers }:
+let
+  sitePkg = runCommand "site" { } ''
+    dist=$out/dist
+    mkdir -p $dist
+    echo "<html><body><a href=\"https://example.com/foo.html\">foo</a></body></html>" > $dist/index.html
+    echo "<html><body><a href=\".\">index</a></body></html>" > $dist/foo.html
+  '';
+in testers.lycheeLinkCheck {
+  site = sitePkg + "/dist";
+  remapUrl = "https://example.com";
+}