Fix unknown options and -- with parse_optionals_as_positionals, and fail on values given both ways

[mauvilsa]

What does this PR do?

Fixes and changes in how extra positionals are parsed with parse_optionals_as_positionals=True:

• An unrecognized option, e.g. name --option value --mistake something, was silently taken as the value of the next optional, or failed with a confusing type error of that optional. Now it fails with unrecognized arguments: --mistake something.
• Values after -- that look like options, e.g. name -- -x, were rejected as unrecognized, and the -- itself could be taken as a value. Now the separator is dropped and everything after it is a positional value.
• Giving a value both by name and as positional, e.g. val1 val2a --o2=val2b, silently used the positional and ignored the named one. Now it fails with an error that names both, e.g. "o2" given both as --o2 and as positional value "val2a". Values from config files, environment variables or defaults are not conflicts, so positionals still override them.
• The provenance of a value given as positional named the option, e.g. --o1, which the user never typed. Now it uses the name shown in the usage, e.g. o1, as for real positionals.

Before submitting

• Did you read the contributing guideline?
• If you used a coding agent, did you fully understand and validate all generated code and ensure it follows the contributing guidelines?
• Did you update the documentation? (readme and public docstrings)
• Did you write unit tests such that there is 100% coverage on related code? (required for bug fixes and new features)
• Did you verify that new and existing tests pass locally?
• If this is a bug fix, did you verify that the tests fail without the code fix?
• Did you make sure that all changes preserve backward compatibility?
• Did you update the CHANGELOG including a pull request link? (not for typos, docs, test updates, or minor internal changes/refactors)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (b1bd6c8) to head (968af0b).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1009   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           27        27           
  Lines         9800      9814   +14     
=========================================
+ Hits          9800      9814   +14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] Changes how optional arguments parse when treated as positionals.

Fix the duplicate check before merging so valid namespace overrides work and configs cannot hide current duplicates.

Findings

1.  Duplicate checks confuse saved sources ▶

Summary

This PR rejects unknown options before assigning extra positional values, treats values after -- as positionals, and records positional sources using their usage names.

• Adds tests and documentation for separators and values supplied both ways.
• The duplicate check needs to distinguish options in the current call from earlier or replaced value sources.

_{Reviews (1) · Last reviewed commit: "Fix unknown options and -- with parse_op..." · Reviewed by Greptile}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud