RFC: local-remote mapping (a possible semantics for --base-url + --root-dir)

[katrinafyi]

I think that at this point, it's known that using base-url and root-dir together is surprising and buggy. Also, base-url alone can be unexpected as well. It would be really nice to improve this. (In fact, it's my underlying motivation for working on lychee :))

In this thread, I want to reach a consensus about what the right or most intuitive behaviour would be for root-dir + base-url, and also make a plan for how to move towards that. This is continuing on from threads #1718 and also #1624.

In the earlier discussions, I think a few of us reached an understanding of the use-case which we would like to solve.

The idea is that there should be a way to teach lychee about a correspondence between some remote URLs and a folder on disk, a kind of mapping from remote to local (or the other way around). @dkarlovi wrote about remote-to-local in
#1718 (comment). I wrote about it at https://lychee.cli.rs/recipes/local-folder/ and #1718 (comment). @MichaIng also wrote about both directions in #1718 (comment).

I think that changing the behaviour of base-url + root-dir is a good place to implement this feature, and this use-case gives a sensible and useful behaviour for the two options.

About base-url, we should keep in mind that a lot of the problems with current base-url are that it applies broadly and indiscriminately, throwing away local filesystem paths. As such, I think that using base-url alone doesn't make much sense - you don't know which local paths to map to the base URL. I'd want to make base-url require root-dir.

Finally, the biggest open question is how do we teach this change to users in the least surprising and jarring way? Will users need any guidance migrating from old base-url? Is anyone even using or relying on the current base-url?

Questions:

• Does this make sense as a behaviour for base-url + root-dir? Are there other possible behaviours?
• Should we support remote-to-local, local-to-remote, or both? Configurable by option?
• Should we re-use the flags or make new flags?
• If we take over base-url, what about input sources without any base (like stdin)? It should be possible to specify a fallback base URL for them, maybe a new flag?
• Should root-dir also apply to local files residing outside of the root directory? Should it also apply to stdin?
• Should we generalise to some idea of URL-based prefix remapping? Because this is kind of just slicing off a base-url prefix and putting root-dir in its place. Maybe later...
• Is this an important feature for lychee or is the workaround at https://lychee.cli.rs/recipes/local-folder/ "good enough"?