Document a design flaw of test, to be fixed

src/Streamly/Coreutils/FileTest.hs

@@ -27,6 +27,11 @@
 -- It offers greater composability and improved performance by allowing
 -- multiple predicates to share a single file status query.
 --
+-- One important difference from the shell utility is that all the predicates
+-- except 'doesItExist' raise an exception if the file does not exist so that
+-- we can distinguish the cases when the predicate is actually false and when
+-- the file does not exist. This is safer and avoids silent bugs.
+--
 -- String comparison tests provided by GNU @test@ are intentionally omitted,
 -- as they can be expressed directly using standard Haskell operators.
 --
@@ -63,10 +68,9 @@
 --
 -- Example:
 --
--- > test path doesItExist
--- > test path isReadable
--- > test path (size (> 4096))
--- > test path (modifyTimeComparedTo (>) "reference.txt")
+-- >>> _ <- test "a" doesItExist
+-- >>> _ <- test "/usr/bin/ls" (isReadable `and_` size (> 4096))
+-- >>> _ <- test "/usr/bin/ls" (modifyTimeComparedTo "reference.txt" (>))
 
 module Streamly.Coreutils.FileTest
     (

src/Streamly/Coreutils/FileTest/Common.hs

@@ -409,6 +409,10 @@ applyCatchENOENT f fs =
         | isDoesNotExistError e = return False
         | otherwise             = throwIO e
 
+-- XXX * Returns 'False' if the file does not exist or the predicate is 'False'
+-- This can lead to silent bugs. We should raise an exception if the file does
+-- not exist unless the predicate is doesItExist.
+
 -- | Apply a predicate to a 'FilePath', if the path is a symlink uses the link
 -- target and not the link itself. See 'testl' for testing the link itself.
 --