review: make index_files an Option for clearer default behavior

this changes all the `index_files` fields to be `Option<Vec<String>>`
instead of only a vec. this lets API users simply pass a None to
get the default behaviour.

documentation at the higher level interfaces (e.g., the CLI help)
is changed to remove reference to `.` as the default behaviour.
now, the default behaviour is defined in terms of its observable
behaviour without reference to this implementation detail.

that said, the index file resolution still has this special case
that `.` is allowed in the `index_files` list. this allows the
(possibly esoteric) case where a user passes `--index-files index.html,.`
to use an index file if it exists but still accept the link regardless.

the None case for index_files is still implemented by mapping
to an index file list of `["."]`, but this is now only an
implementation detail of `apply_index_files`.

finally, using an Option is nicer than special-casing the empty
`Vec<String>` case, because the empty vec case /should/ reject
all directory links. this follows logically because the fewer
items in the index file list, the fewer directory links are valid.

Author: katrinafyi

README.md

@@ -461,25 +461,20 @@ Options:
           Note: This option only takes effect on `file://` URIs which do not exist.
 
       --index-files <INDEX_FILES>
-          When checking locally, resolves directory links to an index file within the
-          directory. The argument is a comma-separated list of index file names to search
-          for. Index files are attempted in the order given, and at least one must exist
-          in order for a directory link to be considered valid.
+          When checking locally, resolves directory links to an index file
+          within the directory. The argument is a comma-separated list of index file
+          names to search for. Index files are attempted in the order given.
 
-          The special name `.` can be used to resolve directory links to the directory
-          itself. When `.` is specified, a directory link will be accepted as long as the
-          directory exists. This is the default behavior.
+          If --index-files is specified, then at least one index file must exist in
+          order for a directory link to be considered valid.
 
-          An empty string can be passed to reject all local directory links. This will
-          require all links to explicitly name an HTML file, rather than linking to a
-          directory.
+          By default, index files are disabled, and directory links are considered valid
+          as long as the directory exists on disk.
 
           Example: --index-files index.html,readme.md
 
           Note: This option only takes effect on `file://` URIs which exist and point to a directory.
 
-          [default: .]
-
   -H, --header <HEADER:VALUE>
           Set custom header for requests
 

lychee-bin/src/options.rs

@@ -563,26 +563,22 @@ Note: This option only takes effect on `file://` URIs which do not exist."
     #[serde(default)]
     #[arg(
         long,
-        default_value = ".",
         value_delimiter = ',',
-        long_help = "When checking locally, resolves directory links to an index file within the
-directory. The argument is a comma-separated list of index file names to search
-for. Index files are attempted in the order given, and at least one must exist
-in order for a directory link to be considered valid.
+        long_help = "When checking locally, resolves directory links to an index file
+within the directory. The argument is a comma-separated list of index file
+names to search for. Index files are attempted in the order given.
 
-The special name `.` can be used to resolve directory links to the directory
-itself. When `.` is specified, a directory link will be accepted as long as the
-directory exists. This is the default behavior.
+If --index-files is specified, then at least one index file must exist in
+order for a directory link to be considered valid.
 
-An empty string can be passed to reject all local directory links. This will
-require all links to explicitly name an HTML file, rather than linking to a
-directory.
+By default, index files are disabled, and directory links are considered valid
+as long as the directory exists on disk.
 
 Example: --index-files index.html,readme.md
 
 Note: This option only takes effect on `file://` URIs which exist and point to a directory."
     )]
-    pub(crate) index_files: Vec<String>,
+    pub(crate) index_files: Option<Vec<String>>,
 
     /// Set custom header for requests
     #[arg(

lychee-lib/src/checker/file.rs

@@ -19,13 +19,17 @@ pub(crate) struct FileChecker {
     base: Option<Base>,
     /// List of file extensions to try if the original path doesn't exist.
     fallback_extensions: Vec<String>,
-    /// List of index file names to search for if the path is a directory.
+    /// If specified, resolves to one of the given index files if the original path
+    /// is a directory.
     ///
-    /// Index files names are required to match regular files, aside from the
-    /// special `.` name which will match the directory itself. This list
-    /// *should* be non-empty, otherwise all directory links will be considered
-    /// invalid due to "cannot find index file".
-    index_files: Vec<String>,
+    /// If non-`None`, a directory must contain at least one of the file names
+    /// in order to be considered a valid link target. Index files names are
+    /// required to match regular files, aside from the special `.` name which
+    /// will match the directory itself.
+    ///
+    /// If `None`, index file checking is disabled and directory links are valid
+    /// as long as the directory exists on disk.
+    index_files: Option<Vec<String>>,
     /// Whether to check for the existence of fragments (e.g., `#section-id`) in HTML files.
     include_fragments: bool,
     /// Utility for performing fragment checks in HTML files.
@@ -39,12 +43,12 @@ impl FileChecker {
     ///
     /// * `base` - Optional base path or URL for resolving relative paths.
     /// * `fallback_extensions` - List of extensions to try if the original file is not found.
-    /// * `index_files` - List of index file names to search for if the path is a directory.
+    /// * `index_files` - Optional list of index file names to search for if the path is a directory.
     /// * `include_fragments` - Whether to check for fragment existence in HTML files.
     pub(crate) fn new(
         base: Option<Base>,
         fallback_extensions: Vec<String>,
-        index_files: Vec<String>,
+        index_files: Option<Vec<String>>,
         include_fragments: bool,
     ) -> Self {
         Self {
@@ -178,26 +182,36 @@ impl FileChecker {
     }
 
     /// Tries to find an index file in the given directory, returning the first match.
+    /// The index file behavior is specified by [`FileChecker::index_files`].
+    ///
+    /// If this is non-`None`, index files must exist and resolved index files are
+    /// required to be files, aside from the special name `.` - this will match the
+    /// directory itself.
     ///
-    /// Resolved index files are required to be files, aside from the special
-    /// name `.` - this will match the directory itself. This permits `.` to be
-    /// specified in [`FileChecker::index_files`] to treat a directory as its own
-    /// index file, accepting the link so long as the directory exists.
+    /// If `None`, index file resolution is disabled and this function simply
+    /// returns the given path.
     ///
     /// # Arguments
     ///
     /// * `dir_path` - The directory within which to search for index files.
-    ///   This is assumed to be a directory.
+    ///   This is assumed to be an existing directory.
     ///
     /// # Returns
     ///
     /// Returns `Ok(PathBuf)` pointing to the first existing index file, or
     /// `Err` if no index file is found. If `Ok` is returned, the contained `PathBuf`
     /// is guaranteed to exist. In most cases, the returned path will be a file path.
-    /// If `.` appears within [`FileChecker::index_files`], then the returned path
-    /// may also be a directory.
+    ///
+    /// If index files are disabled, simply returns `Ok(dir_path)`.
     fn apply_index_files(&self, dir_path: &Path) -> Result<PathBuf, ErrorKind> {
-        self.index_files
+        // this implements the "disabled" case by treating a directory as its
+        // own index file.
+        let index_names_to_try = match &self.index_files {
+            Some(names) => &names[..],
+            None => &[".".to_owned()],
+        };
+
+        index_names_to_try
             .iter()
             .find_map(|filename| {
                 // for some special index file names, we accept directories as well
@@ -304,9 +318,8 @@ mod tests {
 
     #[tokio::test]
     async fn test_default() {
-        // default behaviour from passing "." as index_files.
-        // this accepts dir links as long as the directory exists.
-        let checker = FileChecker::new(None, vec![], vec![".".to_owned()], true);
+        // default behaviour accepts dir links as long as the directory exists.
+        let checker = FileChecker::new(None, vec![], None, true);
 
         assert_filecheck!(&checker, "filechecker/index_dir", Status::Ok(_));
 
@@ -338,7 +351,7 @@ mod tests {
         let checker = FileChecker::new(
             None,
             vec![],
-            vec!["index.html".to_owned(), "index.md".to_owned()],
+            Some(vec!["index.html".to_owned(), "index.md".to_owned()]),
             true,
         );
 
@@ -377,7 +390,7 @@ mod tests {
         let checker = FileChecker::new(
             None,
             vec!["html".to_owned()],
-            vec!["index".to_owned()],
+            Some(vec!["index".to_owned()]),
             false,
         );
 
@@ -411,7 +424,7 @@ mod tests {
     #[tokio::test]
     async fn test_empty_index_list_corner() {
         // empty index_files list will reject all directory links
-        let checker_no_indexes = FileChecker::new(None, vec![], vec![], false);
+        let checker_no_indexes = FileChecker::new(None, vec![], Some(vec![]), false);
         assert_filecheck!(
             &checker_no_indexes,
             "filechecker/index_dir",
@@ -435,7 +448,7 @@ mod tests {
             "..".to_owned(),
             "/".to_owned(),
         ];
-        let checker_dir_indexes = FileChecker::new(None, vec![], dir_names, false);
+        let checker_dir_indexes = FileChecker::new(None, vec![], Some(dir_names), false);
         assert_filecheck!(
             &checker_dir_indexes,
             "filechecker/index_dir",
@@ -456,7 +469,7 @@ mod tests {
         let checker_dotdot = FileChecker::new(
             None,
             vec![],
-            vec!["../index_dir/index.html".to_owned()],
+            Some(vec!["../index_dir/index.html".to_owned()]),
             true,
         );
         assert_filecheck!(

lychee-lib/src/client.rs

@@ -96,17 +96,18 @@ pub struct ClientBuilder {
     /// Index file names to use when resolving `file://` URIs which point to
     /// directories.
     ///
-    /// For local directory links, at least one index file from this list must
-    /// exist in order for the link to be considered valid.
-    ///
-    /// Index files names are required to match regular files, aside from the
-    /// special `.` name which will match the directory itself. In the
-    /// [`ClientBuilder`], this defaults to `["."]`.
-    ///
-    /// This option only takes effect on `file://` URIs which exist and
-    /// point to a directory.
-    #[builder(default = vec![".".to_owned()])]
-    index_files: Vec<String>,
+    /// For local directory links, if this is non-`None`, then at least one
+    /// index file from this list must exist in order for the link to be
+    /// considered valid. Index files names are required to match regular
+    /// files, aside from the special `.` name which will match the
+    /// directory itself.
+    ///
+    /// If `None`, index file checking is disabled and directory links are valid
+    /// as long as the directory exists on disk.
+    ///
+    /// In the [`ClientBuilder`], this defaults to `None`.
+    #[builder(default = None)]
+    index_files: Option<Vec<String>>,
 
     /// Links matching this set of regular expressions are **always** checked.
     ///