Merge pull request #5798 from IntersectMBO/nm/doctesting

Refactor doctesting

Author: lehins

.github/workflows/haskell.yml

@@ -169,6 +169,18 @@ jobs:
         path: ${{ steps.install-haskell.outputs.cabal-store }}
         key:  ${{ steps.restore-cabal-cache.outputs.cache-primary-key }}
 
+    # `doctest` needs to be present before building, to avoid `cabal repl` seeing a configuration
+    # change when `scripts/doctest.sh` runs it
+    - name: Install doctest
+      id: install-doctest
+      if: matrix.ghc == '9.6.7'
+      run: |
+        if [[ -z "$(type -t doctest)" ]]
+        then
+          cabal install doctest --ignore-project --overwrite-policy=always
+          cabal path --installdir >> $GITHUB_PATH
+        fi
+
     - name: Build
       run: cabal build all
 
@@ -189,6 +201,10 @@ jobs:
         overwrite: true
         retention-days: 1
 
+    - name: Run doctests
+      if: ${{ steps.install-doctest.outcome == 'success' }}
+      run: scripts/doctest.sh
+
   test:
     needs: build
 

flake.lock

@@ -146,7 +146,7 @@
 
             # and from nixpkgs or other inputs
             nativeBuildInputs = with nixpkgs;
-              [
+              with (import nix/doctest.nix { inherit config nixpkgs; }); [
                 (python3.withPackages (ps:
                   with ps; [
                     sphinx
@@ -158,18 +158,9 @@
                 haskellPackages.implicit-hie
                 shellcheck
                 act
+                doctest
                 inputs.cardano-ledger-release-tool.packages.${system}.default
-              ] ++ (let
-                doctest = haskell-nix.hackage-package {
-                  name = "doctest";
-                  version = "0.24.3";
-                  configureArgs = "-f cabal-doctest";
-                  inherit (config) compiler-nix-name;
-                };
-              in [
-                (doctest.getComponent "exe:cabal-doctest")
-                (doctest.getComponent "exe:doctest")
-              ]);
+              ];
             # disable Hoogle until someone request it
             withHoogle = false;
             # Skip cross compilers for the shell

flake.nix

@@ -64,7 +64,9 @@ gTwiddleTList v a = TList <$> twiddleL v (from @a @p a)
 --
 --   For any value `x :: a`, where `a` derives `Twiddle`, and for any version
 --   of the decoder, the following property must hold:
---   >>> fmap ((== x) . encodingToTerm version . encCBOR) (twiddle x)
+--   prop> \x version -> fmap (== encodingToTerm version (encCBOR x)) (twiddle version (x :: Double))
+--
+--   Note: this property doesn't hold for some types, hence the type restriction
 class Twiddle a where
   -- | Given a value of type `a`, generates a CBOR `Term` that can contain
   -- slight variations without changing the semantics. After encoding and

libs/cardano-ledger-binary/testlib/Test/Cardano/Ledger/Binary/Twiddle.hs

@@ -67,6 +67,7 @@ class
   --
   -- Designed to be used with @TypeApplications@:
   --
+  -- >>> :set -XTypeApplications
   -- >>> eraName @ByronEra
   -- "Byron"
   eraName :: String

libs/cardano-ledger-core/internal/Cardano/Ledger/Internal/Definition/Era.hs

@@ -0,0 +1,17 @@
+# Provide a custom-built doctest that's compatible with haskell.nix
+
+{ config, nixpkgs }:
+
+let
+  doctest = nixpkgs.haskell-nix.hackage-package {
+    name = "doctest";
+    version = "0.24.3";
+    inherit (config) compiler-nix-name;
+    modules = [{
+      packages = {
+        # This enables doctest to find ghc etc. via environment variables
+        ghc-paths.patches = nixpkgs.haskellPackages.ghc-paths.patches;
+      };
+    }];
+  };
+in { doctest = doctest.getComponent "exe:doctest"; }

nix/doctest.nix

@@ -5,10 +5,11 @@ set -euo pipefail
 # Packages to run doctests for; defaults to all packages if none are specified
 PACKAGES=("$@")
 
-# Install doctest's Cabal integration, if it's not present already
-if [[ -z "$(type -t cabal-doctest)" ]]
+# Install doctest, if it's not present already
+if [[ -z "$(type -t doctest)" ]]
 then
-  cabal install doctest --flag cabal-doctest --ignore-project --overwrite-policy=always
+  cabal install doctest --ignore-project --overwrite-policy=always
+  PATH=$(cabal path --installdir):$PATH
 fi
 
 # Ensure doctest and PATH are using the same ghc version
@@ -18,8 +19,18 @@ getExecutablePath()
   "$1" -package-env - -e 'import System.Environment' -e 'putStrLn =<< getExecutablePath'
 }
 
+lookupVar()
+{
+  ghc -e 'interact $ maybe "" id . lookup "'"$1"'" . read'
+}
+
+getPackageDb()
+{
+  readlink -f "$("$1" --info | lookupVar 'Global Package DB')"
+}
+
 default_ghc=$(type -p ghc)
-doctest_ghc=$(doctest --info | ghc -e 'interact $ maybe "" id . lookup "ghc" . read')
+doctest_ghc=$(doctest --info | lookupVar 'ghc')
 
 if [[ "$(getExecutablePath "$default_ghc")" != "$(getExecutablePath "$doctest_ghc")" ]]
 then
@@ -29,13 +40,25 @@ then
   exit 1
 fi
 
-# Ensure the cabal-doctest executable can be found
-PATH=$(cabal path --installdir):$PATH
+if [[ "$(getPackageDb ghc)" != "$(getPackageDb doctest)" ]]
+then
+  echo "Incompatible package DBs:" >&2
+  echo "  Default DB: $(getPackageDb ghc)" >&2
+  echo "  Doctest DB: $(getPackageDb doctest)" >&2
+  exit 1
+fi
 
-# Ensure other scripts can be found
-case "$0" in
-  */*) PATH=$(dirname "$(which "$0")"):$PATH;;
-esac
+# Find packages potentially containing doctests
+if [[ ${#PACKAGES[@]} -eq 0 ]]
+then
+  for CABAL_FILE in $(git ls-files '*.cabal')
+  do
+    if git grep -qIEe '(>>>|prop>)' "${CABAL_FILE%/*}/*.hs"
+    then
+      PACKAGES+=("$(basename "$CABAL_FILE" .cabal)")
+    fi
+  done
+fi
 
 # Specify additional arguments needed for specific modules
 EXTRA_ARGS=$(mktemp)
@@ -44,11 +67,18 @@ cat <<EOF >"$EXTRA_ARGS"
 cardano-ledger-api:lib:cardano-ledger-api --build-depends=cardano-ledger-babbage:testlib
 EOF
 
+RESULT=0
+shopt -s lastpipe # Run the while loop in the current process, to enable setting RESULT=1
+
 # Run the doctests for some or all packages
 cleret cabal targets "${PACKAGES[@]}" |
 sort | join -t' ' -a1 -j1 - "$EXTRA_ARGS" |
 while read -ra ARGS
 do
   echo "***** cabal doctest ${ARGS[0]} *****"
-  cabal doctest --repl-options='-w -Wdefault' "${ARGS[@]}"
+  cabal repl --with-repl=doctest --repl-options='-w -Wdefault' \
+    --build-depends=QuickCheck --build-depends=template-haskell \
+      "${ARGS[@]}" || RESULT=1
 done
+
+exit "$RESULT"