[fire-mirror]

Closes #3926.

Problem

With unstable string processing enabled, a long string return annotation is initially
wrapped in optional parentheses so StringSplitter can split it. When the function's
parameters also require a left-hand split, the optional parentheses are removed before
the return annotation reaches StringSplitter. The annotation is then left on an
overlong line.

Changes

• Preserve optional parentheses for plain string return annotations when the parameter
  list is split, allowing the existing string-processing pipeline to split the
  annotation.
• Reuse StringSplitter's breakpoint rules so literals without a legal split remain
  unchanged.
• Keep static-analysis pragma comments attached to their original logical line instead
  of sending them through the string-splitting path.
• Track matching brackets on the tail produced by bracket splitting so the preserved
  pair remains visible to subsequent transformers.
• Keep triple-quoted return annotations unchanged because StringSplitter cannot split
  them, with regression coverage for that boundary.

The change is limited to the unstable string-processing path and retains the existing
public API.

Validation

• tests/test_format.py: 236 passed
• tests/test_trans.py: 1 passed
• focused preview_return_annotation_brackets_string fixture: 1 passed
• pre-commit run --files src/black/linegen.py src/black/trans.py tests/data/cases/preview_return_annotation_brackets_string.py CHANGES.md: all hooks passed
• Reproduced the original overlong output on the base commit; the fixed output splits
  the annotation and is stable on a second formatting pass.
• Covered regular, unsplittable, triple-quoted, # noqa, and # type: ignore return annotations.

Checklist

• The style change is under the --unstable/preview style policy.
• Added a CHANGES.md entry.
• Added regression coverage.
• No documentation update is needed for this bug fix.

[github-actions]

diff-shades results comparing this PR (61fc6b4) to main (20622e1):

--preview style: no changes

--stable style: no changes

---

What is this? | Workflow run | diff-shades documentation