feat!: Block using --base-url with --root-dir and suggest alternative

[katrinafyi]

I want to make changes to these options so that they interact more sensibly. I want this to happen in stages so that it's easier to review and discuss, but each stage might change the behaviour of --base-url and --root-dir.

I don't want users who might be using these options to discover that it's changed and then adapt to the new behaviour, only for it to be changed again later. I'd like it to all be locked down until we finish the changes we want to make, and then we can present it as a polished new feature with a well-defined behaviour.

Given the bugs currently in these options (base-url in particular), I don't think anyone is using these flags together.

Github code search turns up only one YML file which is using this combination of options:
https://github.com/search?q=%22--base-url%22+%22--root-dir%22+lychee+language%3AYML&type=code

The error message is:

Error: Using root-dir and base-url together is not (yet) supported.
Hint: In most cases, root-dir is sufficient and base-url should be
removed. If you need to map a remote URL into a local folder, see
https://lychee.cli.rs/recipes/local-folder/

TODO: update website!!!!

Possible issues:

• The example TOML file has all options defined. This change means that trying to load the example TOML config into lychee will fail. I don't know if there's a good way around this, maybe it can just drop one of the options (with a warning, ofc).

[mre]

Yes, what you have so far makes sense to me. Thanks for doing the user research.

The example TOML file has all options defined. This change means that trying to load the example TOML config into lychee will fail. I don't know if there's a good way around this, maybe it can just drop one of the options (with a warning, ofc).

Isn't the assumption that both options shouldn't be used in combination anyway? If so, we could just update the config file by commenting out base-url and updating the docs accordingly, so people can still learn about it.

[katrinafyi]

It turns out that the example toml doesn't raise an error, because it sets dump_inputs = true and this avoids the code where we check for base-url + root-dir. This seems fine, the toml is not meant to be a practical working example anyway.

I've made some more small fixes to the toml and help text.

[katrinafyi]

Hm maybe this doesn't need to be an error in this case, it would make it harder to test and keep an eye on changes. Maybe it can just be a warning. Idk

[thomas-zahner]

@katrinafyi Thank you for your thinking. I'm fine with both an error and a warning. Admittedly, I even think it's okay to introduce a breaking change for these args without the effort of introducing such a temporary warning/error. We're still not at version 1 and as you pointed out there is almost nobody out there using both options in combination, so it would be fine to impose a breaking change on those very few users without the hassle of this PR.

[thomas-zahner]

What's the reason for this?

[katrinafyi]

So it can be omitted from the example TOML, I don't think most users will want this.

[thomas-zahner]

Ah of course, I see. It would indeed be a very unusual use-case, didn't think of it in the UX perspective.

Then maybe?

Suggested change

	"generate", // special use argument
	"generate", // valid but unusual use-case