fix: prefix_command should not stop parsing at unrecognized options (#1374)

[henryiii]

🤖 AI text below 🤖

Fixes #1374.

prefix_command(true) changed behavior between 2.5.0 and 2.6.2. Since #1266 (2.6.2), the first unrecognized option caused all remaining tokens — including registered options — to be swept into extras, so whether a registered option was recognized depended on its position relative to unknown ones. This broke ParaView/VTK, which uses prefix_command + allow_extras to pick out the handful of options registered so far, wherever they appear, before a later re-parse.

This restores the long-standing behavior: only a positional argument or the -- separator stops parsing; an unrecognized option is collected as an extra and parsing continues.

The SeparatorOnly mode added in #1266 already covers the strict case from #1264 and is unchanged. The prefix_command docstring, which incorrectly claimed parsing stopped at the first unrecognized option, is corrected.

A regression test covering the issue's order-independence scenario was added, and the one existing assertion that had locked in the 2.6.2 behavior was updated.

[henryiii]

@phlptp thoughts? This was changed in 2.6.2. We could introduce a new mode for the strict stop at any option mode. Or we could reintroduce the old mode, though that's more churn since this has only been out in one patch release. (This PR is just the revert, but any path is possible)

[phlptp]

the prefix_command mode has caused a bit of confusion over time. I remember several issues raised of it not working as expected and the previous behavior being confusing to people. So the previous behavior caused some issues and confusion, especially when used in combination with fallthrough and allow_extras. The current behavior made that clear to better match the documentation, but I guess there were those depending on the nuances of the behavior. I think the intended case is putting prefix_command on a subcommand with no option so that command dumps everything remaining since there are no valid options after that, or with a new mode using -- the complexity comes when adding prefix_command on an app/subcommand with existing options or fallthrough or allow_extras that it can interact with the parent options and get some odd behavior. I think my preference would be to leave the current behavior as is, as I would argue that it is clearer than before, and to address this issue add a PositionalOnly mode that turns off the while loop for unknown arguments.