ftw: Clarify the behavior of `scandir' for flat files and unreadable dirs.

* module/ice-9/ftw.scm (scandir)[leaf]: Only add NAME when RESULT is a
  pair.
  [down]: Ignore RESULT.
  Start with #f instead of the empty list.

* test-suite/tests/ftw.test ("scandir")["flat file"]: New test.

* doc/ref/misc-modules.texi (File Tree Walk): Update `scandir'
  documentation accordingly.

doc/ref/misc-modules.texi

@@ -1254,7 +1254,8 @@ Return the list of the names of files contained in directory @var{name}
 that match predicate @var{select?} (by default, all files).  The
 returned list of file names is sorted according to @var{entry<?}, which
 defaults to @code{string-locale<?} such that file names are sorted in
-the locale's alphabetical order (@pxref{Text Collation}).
+the locale's alphabetical order (@pxref{Text Collation}).  Return
+@code{#f} when @var{name} is unreadable or is not a directory.
 
 This procedure is modeled after the C library function of the same name
 (@pxref{Scanning Directory Content,,, libc, GNU C Library Reference

module/ice-9/ftw.scm

@@ -512,17 +512,18 @@ children.  The optional STAT parameter defaults to `lstat'."
   "Return the list of the names of files contained in directory NAME
 that match predicate SELECT? (by default, all files.)  The returned list
 of file names is sorted according to ENTRY<?, which defaults to
-`string-locale<?'."
+`string-locale<?'.  Return #f when NAME is unreadable or is not a directory."
   (define (enter? name stat result)
     (and stat (string=? name name)))
 
   (define (leaf name stat result)
     (if (select? name)
-        (cons (basename name) result)
+        (and (pair? result)                      ; must have a "." entry
+             (cons (basename name) result))
         result))
 
   (define (down name stat result)
-    (cons "." result))
+    (list "."))
 
   (define (up name stat result)
     (cons ".." result))
@@ -531,7 +532,7 @@ of file names is sorted according to ENTRY<?, which defaults to
     ;; NAME itself is not readable.
     #f)
 
-  (and=> (file-system-fold enter? leaf down up skip '() name stat)
+  (and=> (file-system-fold enter? leaf down up skip #f name stat)
          (lambda (files)
            (sort files entry<?))))
 

test-suite/tests/ftw.test

@@ -173,4 +173,7 @@
     (let ((select? (cut string-suffix? ".test" <>)))
       (match (scandir (string-append %test-dir "/tests") select?)
         (("." ".." "00-initial-env.test" (? select?) ...)
-         #t)))))
+         #t))))
+
+  (pass-if "flat file"
+    (not (scandir (string-append %test-dir "/Makefile.am")))))