feat(base-url)!: disallow relative local base to avoid confusion (#1857)

* feat(base-url)!: disallow relative directory paths in `--base-url`

the previous behaviour accepted relative directory paths as bases
but this led to later InvalidBaseJoin errors, because relative paths
cannot be used to join relative URLs. this means that relative local
bases were *only* useful for resolving root-relative links, and were
confusingly problematic with ordinary relative links.

see https://www.github.com/lycheeverse/lychee/issues/1574 which talks about
errors when passing `--base ../network-documentation/` or, in a later
comment, `--base build`.

also, the previous behaviour would parse something like
`--base-url google.com` to a local base pointing to `./google.com`.
this would also lead to downstream errors and it's better to guard
against this.

it is my opinion that it is better to fail earlier in these cases, so
the user is not hit with mysterious InvalidBaseJoin.

after this pr, there will be a command-line argument parsing error:
```
error: invalid value 'build' for '--base-url <BASE_URL>': Error with
base dir `build` : Base must either be a URL (with scheme) or an
absolute path. Alternatively, if you want to resolve root-relative links
in local files, see `--root-dir`.
```

in a slightly opinionated touch, i've mentioned --root-dir in the error
message, since i think --root-dir is more suitable for most use cases
where people try to use relative local bases. this agrees with later
comments in https://www.github.com/lycheeverse/lychee/issues/1574.

however, this does make the error message quite long. so i'm happy to
take on feedback and changes about this.

this pr implements (1) in my outline to reduce InvalidBaseJoin
confusion, as described in
https://www.github.com/lycheeverse/lychee/pull/1624#issuecomment-3274485963

* clippy

* clipy 2

* review: add --help mention 

TODO: probably mention these restrictions and suggestions in --help too

* add sentence to --help

* move CLI-related suggestions into .context in lychee-bin

this does have the side-effect of attaching the --help and --root-dir
suggestions even to the "cannot be a base" error.

```
error: invalid value 'a:datafdajsio' for '--base-url <BASE_URL>': Error
with base dir `a:datafdajsio` : The given URL cannot be used as a base
URL. See `--help` for more information. If you want to resolve
root-relative links in local files, also see `--root-dir`.
```

this could be a bit confusing, but idk a way around it without
inspecting the error message of InvalidBase to determine which context
to add.

* shuffle extra notes about --base-url to the end of its help, and

add a sentence about URL schemes to cover the "cannot be a base"
error.

Author: katrinafyi

README.md

@@ -596,6 +596,9 @@ Options:
           Basically, the base URL option resolves links as if the local files were hosted
           at the given base URL address.
 
+          The provided base URL value must either be a URL (with scheme) or an absolute path.
+          Note that certain URL schemes cannot be used as a base, e.g., `data` and `mailto`.
+
       --root-dir <ROOT_DIR>
           Root directory to use when checking absolute links in local files. This option is
           required if absolute links appear in local files, otherwise those links will be

lychee-bin/src/options.rs

@@ -750,7 +750,10 @@ of the base URL. For example, a base URL of `https://example.com/dir/page/` and
 a link of `a` would resolve to `https://example.com/dir/page/a`.
 
 Basically, the base URL option resolves links as if the local files were hosted
-at the given base URL address."
+at the given base URL address.
+
+The provided base URL value must either be a URL (with scheme) or an absolute path.
+Note that certain URL schemes cannot be used as a base, e.g., `data` and `mailto`."
     )]
     #[serde(default)]
     pub(crate) base_url: Option<Base>,

lychee-bin/src/parse.rs

@@ -13,8 +13,20 @@ pub(crate) fn parse_remaps(remaps: &[String]) -> Result<Remaps> {
         .context("Remaps must be of the form '<pattern> <uri>' (separated by whitespace)")
 }
 
-pub(crate) fn parse_base(src: &str) -> Result<Base, lychee_lib::ErrorKind> {
-    Base::try_from(src)
+pub(crate) fn parse_base(src: &str) -> Result<Base> {
+    match Base::try_from(src) {
+        Ok(x) => Ok(x),
+        Err(e) => {
+            // if context is defined, clap displays only the context string in
+            // argument parse errors. to keep the message from within InvalidBase,
+            // we need to retain it manually.
+            let message = format!(
+                "{e}. See `--help` for more information. If you want to resolve \
+                root-relative links in local files, also see `--root-dir`."
+            );
+            Err(e).context(message)
+        }
+    }
 }
 
 #[cfg(test)]

lychee-lib/src/types/base.rs

@@ -56,12 +56,24 @@ impl TryFrom<&str> for Base {
             if url.cannot_be_a_base() {
                 return Err(ErrorKind::InvalidBase(
                     value.to_string(),
-                    "The given URL cannot be a base".to_string(),
+                    "The given URL cannot be used as a base URL".to_string(),
                 ));
             }
             return Ok(Self::Remote(url));
         }
-        Ok(Self::Local(PathBuf::from(value)))
+
+        // require absolute paths in `Base::Local`. a local non-relative base is
+        // basically useless because it cannot be used to join URLs and will
+        // cause InvalidBaseJoin.
+        let path = PathBuf::from(value);
+        if path.is_absolute() {
+            Ok(Self::Local(path))
+        } else {
+            Err(ErrorKind::InvalidBase(
+                value.to_string(),
+                "Base must either be a URL (with scheme) or an absolute local path".to_string(),
+            ))
+        }
     }
 }
 
@@ -96,14 +108,23 @@ mod test_base {
 
     #[test]
     fn test_valid_local_path_string_as_base() -> Result<()> {
-        let cases = vec!["/tmp/lychee", "/tmp/lychee/", "tmp/lychee/"];
+        let cases = vec!["/tmp/lychee", "/tmp/lychee/"];
 
         for case in cases {
             assert_eq!(Base::try_from(case)?, Base::Local(PathBuf::from(case)));
         }
         Ok(())
     }
 
+    #[test]
+    fn test_invalid_local_path_string_as_base() {
+        let cases = vec!["a", "tmp/lychee/", "example.com", "../nonlocal"];
+
+        for case in cases {
+            assert!(Base::try_from(case).is_err());
+        }
+    }
+
     #[test]
     fn test_valid_local() -> Result<()> {
         let dir = tempfile::tempdir().unwrap();