[FEATURE] Support :lines: in literalinclude

[CybotTM]

Builds on #1351 and contains its two commits, so only the last two commits are new here — see the commit list. Please review #1351 first; I will rebase this one onto main once that is merged.

What this adds

The Sphinx option :lines: for literalinclude, so a region can also be selected by line number:

..  literalinclude:: Example.php
    :language: php
    :lines: 1,3-5,20-

Line numbers are 1 based, ranges are inclusive, an omitted end means "up to the last line", and overlapping ranges are included once, in document order. Both ends are clamped to the lines that exist, so :lines: 1-99999999999 selects the whole region instead of iterating over the number the author wrote down.

The accepted spelling is validated with DefaultCodeNodeOptionMapper::LINE_NUMBER_RANGES_REGEX, the pattern already used for :emphasize-lines:, so both options are written the same way. If you would rather not have the directive reference the mapper's constant, say so and I will move the pattern to a shared place.

Order of application

Like Sphinx, :lines: is applied after :start-after: and :end-before:, so the numbers count within the marked region rather than within the file. There is an integration test for that combination.

I would still describe markers as the more valuable half of this: line numbers break on every edit above the selected region, markers do not. :lines: is here for Sphinx compatibility and for files that have no natural marker.

Behaviour on an invalid or empty selection

Each range that selects no line is warned about on its own, naming that range, and the remaining ranges are still included — :lines: 1-2,100 on a 15 line file includes lines 1 and 2 and says that 100 selected nothing. A missing value or a value that is not a list of line numbers logs a warning and includes nothing, consistent with a marker that is not found in #1351.

Documentation

The reference page added in #1351 gets a section on selecting lines by number, including the order of application and the advice to prefer markers where a file has them.

Tests

Eight integration tests: a mixed range list, an open ended range, an invalid specification, a range beyond the end of the file, a range list where only one entry is beyond the end, :lines: used without a value, a range far beyond PHP_INT_MAX territory as a regression test for the clamping, and :lines: combined with markers.

Local run of phpunit (unit, functional, integration), phpcs, phpstan and deptrac: green.

Assisted by claude-code:claude-opus-5 — Session

[linawolf]

Coverage gap: there are existing tests for :linenos:/:lineno-start: in isolation, but none combine it with the new :lines:/:start-after:/:end-before: filtering. Checked against Sphinx's LiteralIncludeReader -- :lineno-start: is meant to be a plain override independent of filtering (no :lineno-match: equivalent exists here), so I believe current behavior is already correct, just untested. Worth adding one fixture combining them, e.g. :start-after: + :lines: + :lineno-start: 10, asserting the output numbers from 10 regardless of where the selected content sat in the source file.

[linawolf]

literalinclude-lines-huge-range uses :lines: 1-99999999999 (~10^11) as the regression test for clamping "far beyond PHP_INT_MAX territory," but that value doesn't actually exceed PHP_INT_MAX on 64-bit systems (~9.2x10^18) -- it's off by about 7 orders of magnitude. A genuinely overflowing value clamps correctly today (checked manually), but that path has no test coverage, so a future change to parseRange()'s arithmetic could silently reintroduce overflow behavior undetected. Suggest bumping the value to something that actually exceeds PHP_INT_MAX on 64-bit systems, e.g. 1-99999999999999999999.