[kokokoXUY]

Description

Part of #4052. Two things kept --line-ranges from selecting the right lines when
the first formatting pass rewrote the start of a file.

1. The lines before the first matching block were recorded as an unchanged block

_calculate_lines_mappings marked that region as unchanged even though those lines
have no counterpart on the other side of the diff. A requested range that overlaps
them was therefore mapped by offset instead of being expanded to the changed block,
which is what every other changed block does, and what adjusted_lines' docstring
documents.

2. Lines were compared verbatim

The first pass re-indents the bodies of the statements it formats, so a line that
only moved within its statement looked like an unrelated change. That turned the
whole file into a single leading block, and mapping the range stayed a no-op. The
comparison ignores leading whitespace now: a line that only moved is still the same
line, and _LinesMapping only records where it went.

Together they fix the first case of the issue:

def restrict_to_this_line(arg1,
  arg2,
  arg3):
  print  ( "This should not be formatted." )
  print  ( "This should not be formatted." )

With --line-ranges=1-3, before: the signature is joined and both print
statements are formatted, although they were never selected. After: the signature is
joined, and the print statements keep the indentation given by the first pass
without being formatted.

The lines before the first matching block can also disappear entirely, because Black
drops leading empty lines; a selection that only covers them then maps to nothing.
format_str passed those empty ranges to the second pass, where an empty lines
means "format the whole file", so the file was reformatted in full. The second pass
is now skipped when none of the requested lines survive the first pass.

tests/test_ranges.py expected [(1, 1)] to be unchanged when the first line is
removed; that line has no counterpart in the modified source, so the case now expects
an empty range. A new parametrized test covers the joined statement at the start of a
file, and end-to-end tests pin both the fixed selection and the "nothing survives"
case.

Checklist - did you ...

• Follow the stability policy? This changes --line-ranges line selection, not Black's formatting style.
• Add an entry in CHANGES.md? Added under Unreleased ### Stable style.
• Add / update tests?
• Add new / update outdated documentation? Not needed: adjusted_lines' docstring already describes the intended expansion behaviour.

Verification: pytest tests/test_ranges.py -q -p no:randomly → 42 passed;
pytest tests/test_black.py -q -p no:randomly → 189 passed, 10 subtests passed;
pytest tests/test_format.py -q -p no:randomly → 258 passed; the full suite except
tests/test_blackd.py (needs the d extra) → 505 passed, 3 skipped; black --check
on the touched files is clean. A six-case start-of-file battery produces
byte-identical formatted output to main; the outputs this PR changes are pinned by
the new end-to-end tests.

Disclosure: this change was prepared with an AI coding assistant (DeepSeek) under my direction; I reviewed the diff and the commands above before pushing.

[github-actions]

diff-shades results comparing this PR (c5eb662) to main (1ed66a8):

--preview style: no changes

--stable style: no changes

---

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

[cobaltt7]

Thanks!