fix: Avoid infinite loop when cross-reference keyspace is exhausted

[jonashaag]

For reviewers

• I did not use AI
• I used AI and thoroughly reviewed every code/docs change

Description of the change

Cross-reference stash keys start with _ and preserve the rendered identifier length. One-character and two-character identifiers therefore share a keyspace of only 62 keys. Once all keys are present, _gen_stash_key retries random choices forever.

This became reproducible for attribute values after 2.0.5 started rendering their source-level names: a large value containing more than 62 references through the same one-character module alias hangs the documentation build.

Detect an exhausted key length and expand subsequent keys by one character. Non-exhausted keyspaces retain the existing same-length behavior.

Validation:

• Focused rendering tests: 42 passed.
• Full test suite: passed.
• Downstream strict MkDocs build with 75 one-character alias references: passed.

Relevant resources

• Unrelated CI fixes discovered during validation were split into ci: Fix test matrix compatibility #335.

[jonashaag]

CI follow-up: the unrelated matrix failures are fixed in separate commits. Snapshot fixtures are checked out with LF on Windows; the docs inventory is only consumed by highest-resolution jobs; the global PyO3 ABI3 override was removed so current Pydantic builds on Python 3.15; and lowest-direct is limited to Python 3.10–3.13 because the minimum Pydantic stack cannot build on 3.14/3.15. The latest run is 31/31 green: https://github.com/mkdocstrings/python/actions/runs/29655904249

[pawamoy]

Thanks for the contribution @jonashaag. Can you please send the CI fixes in another PR? And can you also tell your agent to follow our PR template?

[jonashaag]

Done, thanks. I split the unrelated CI fixes into #335 and updated this PR description to follow the repository template.

[jonashaag]

Should we instead just increase the key length statically? Seems much simpler and then we could also remove the preexisting containment check?

[pawamoy]

What do you mean by statically? Just increase the minimum key length? The issue with that is that we risk having the code formatter split lines when it shouldn't. Arguably this is a rare enough case, so if increasing by one (min length 2) solves your issue, we can consider it.

[jonashaag]

Ah ok I wasn't aware. It fixes my issue but of course it's not a general fix... not sure, your call.

[pawamoy]

Let's do that. Increasing to min length 2 means 62*62 possible values (3844), it's very unlikely that someone will render a value with that many names in it. And very short variable/parameter/etc. names are rare enough that it shouldn't be too bad of an issue with formatting 👍

Do you want to update this PR? You can revert everything and just update max(1, length - 1) to max(2, length - 1).