[Feature] Peer requirement explain command filter flag

[jnoordsij]

• [ ] I'd be willing to implement this feature (contributing guide)
• [x] This feature is important to have in this repository; a contrib plugin wouldn't do

Describe the user story

In the v4.3.0 the peer requirement and warning system was restored and reworked (and I think the result is great!). While going to check my projects for possible peer requirements related warning, I however ran into the issue that running the suggested yarn explain peer-requirements command to debug violations, I was presented with a very long list of peer requirements with almost all of them fulfilled. Due to the size of the output, it is now very hard to find the unfulfilled requirements quickly.

Given that I expect such a long result to appear even in small sized projects (i.e. as soon as you use any kind of framework or tooling), and that I think the first use-case for this command will be to check for unfulfilled peer requirements (especially with the yarn install warning message triggering people to check this), having an output containing only unfulfilled requirements might be a lot easier to use.

Describe the solution you'd like

1. Allow an optional flag to be passed to the yarn explain peer-requirements command; e.g. --unfulfilled
2. Update the yarn install warning message to include this flag, so users are prompted to check those by default

Alternatively, the default behavior of the command may be altered to only show unfulfilled requirements by default, with some flag to show all requirements.

Another alternative implementation might be a filter argument that allows filtering in different ways; e.g. all, fulfilled or unfulfilled.

Describe the drawbacks of your solution

This will require some additional tracking of fulfilling state on the requirements when parsing the output, which I assume is not too much of an issue.

The main burden in term of maintenance is having another flag to define, document and be aware of whenever adjusting this command, given that having more flags is known to raise complexity quite fast.

However, to repeat, given that I assume that listing unfulfilled requirements is probably the main use-case for this command, I think this outweighs the drawbacks.

Describe alternatives you've considered

Using grep ✘ is an easy way to filter the output to only list failing requirements; however this is heavily implementation-dependent and thus does not feel like a long-term solution.

[clemyan]

It is unfortunately an inconvenience I've noticed but didn't have time to rigorously improve upon before 4.3.0 was released.

Ideally, the explain peer-requirements command would have a suite of filters so the user can control which requirements to see. (E.g. requirement on the current workspace only, or requirements of <package> only) Unfortunately, because "peer list" (explain peer-requirements) and "peer detail" (explain peer-requirements <hash>) are actually the same command, any flag that is added must make sense for both. If we add filtering flags to "list", the "detail" command would need to either ignore those flags or handle the possibility of the selected peer requirement not matching the filters.

IMO ultimately the solution would be to split the two into two commands but as far as I can tell that requires changing the command path, which would be a breaking change.

That said, since there are similar concerns for the "detail" command in #6205, I'd say a flag that controls whether to only show unsatisfied requirements/requests would make sense for both commands. (/cc @SimenB and @brianlenz)

That leaves a few things to be decided:

1. Given that the primary use case for these commands is to investigate peer requirement warnings, should the default behavior be "failing only"?
2. If "failing only" is the default, what should be the name of the flag? --verbose? --all? Conversely, if "all" is the default, what should be the name of the flag? --unfulfilled? --unsatisfied? --failing?

[kherock]

I was thinking about this after I noticed all of the new output and I think that a separate command sounds the most attractive since it might be nice to have a command that errors when unfulfilled peer requirements exist? It would be nice to have an optional way of enforcing proper dependency trees in CI if the explanation is actionable on its own

[brianespinosa]

--failed-only could also be an option.

I desperately need to be able to filter this list too. I am in a large monorepo environment and there are hundreds of peerDependencies to filter through to find the one or two that have the actual problem.

It would also be great if there was a way to configure in yarnrc.yml the preferred output for this command. For instance if we wanted to always show failed only for the output.

The install output might also be improved.

YN0086: │ Some peer dependencies are incorrectly met by dependencies; run yarn explain peer-requirements for details.

could become something more specific like:

YN0086: │ 8 peer dependencies are incorrectly met by dependencies; run yarn explain peer-requirements for details.

For anyone else landing here, a way to achieve this for now is by running grep for the failed lines like this:

yarn explain peer-requirements | grep '✘'