Support line-range formatting (lines kwarg and jlfmt --lines) (#1100)

Add a way to restrict formatting to specific line ranges, emitting all
other lines verbatim. This is useful for formatting only the lines
touched by a PR/diff, enforcing "newly-changed code must be formatted"
in CI without churning unrelated lines, and backing the LSP 3.18
`textDocument/rangesFormatting` capability (multiple ranges per
request).

- Core API: a `lines` keyword on `format_text` accepting a collection of
inclusive, 1-based `(start, stop)` tuples and/or ranges, e.g.
`format_text(text; lines = [(1, 10), (42, 47)])`. Overlapping and
adjacent ranges are merged.
- CLI: a repeatable `--lines=<start>:<stop>` flag forwarding to the
`lines` kwarg. Limited to a single input file (or stdin); it can not be
combined with multiple inputs/directories or Markdown.

Rather than teaching the formatting pipeline about line ranges, the
feature is kept orthogonal to it (the approach Runic.jl takes): marker
comments are inserted around the requested ranges, the whole text is
formatted as usual so in-range code reflows in its real context, and the
result is spliced back together line by line -- formatted lines between
markers, original source verbatim elsewhere, markers dropped. Line
comments are used as markers so they reliably survive on their own line.

- Closes #191 
- Closes #1099

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Penelope Yong <penelopeysm@gmail.com>

Author: 3 people

HISTORY_v2.md

@@ -2,6 +2,8 @@
 
 Improved usage messages for the `jlfmt` command-line tool. (#1098)
 
+Added the ability to format only specific lines of a file, either via the `--lines` option to `jlfmt`, or the `lines` keyword argument to `format_text()`. (#191, #1099, #1100)
+
 # v2.6.15
 
 Fixed a bug where the combination of `always_use_return` and `short_circuit_to_if` would silently change the meaning of a programme. (#887, #1096)

docs/src/cli.md

@@ -25,10 +25,7 @@ julia -m JuliaFormatter [<options>] <path>...
 ```
 
 !!! note "Runic Compatibility"
-    The CLI interface is designed to be compatible with [Runic.jl](https://github.com/fredrikekre/Runic.jl)'s CLI where possible, making it easier to switch between formatters.
-
-    !!! warning "Missing features"
-        Note that the `--lines` option is not yet implemented.
+    The CLI interface is designed to be compatible with [Runic.jl](https://github.com/fredrikekre/Runic.jl)'s CLI where possible, making it easier to switch between formatters. This includes the repeatable `--lines=<start>:<stop>` option for formatting only specific line ranges (e.g. `jlfmt --lines=1:10 --lines=42:47 src/file.jl`).
 
 ## Quick Start
 

docs/src/skipping_formatting.md

@@ -30,7 +30,7 @@ Note that the formatter expects `#! format: on` and `#! format: off` to be on it
 !!! note "Ignoring files"
     You can also ignore entire files and directories by supplying [the `ignore` option](@ref options-ignore) in `.JuliaFormatter.toml`.
 
-### Preventing indentation
+## Preventing indentation
 
 Sometimes you may wish for a block of code to not be indented.
 You can achieve this with a more targeted approach of `#! format: noindent`.
@@ -89,3 +89,61 @@ end
 ```
 
 `#! format: noindent` can also be nested.
+
+## One-off range formatting
+
+Sometimes it is quite useful to only format specific ranges of a file.
+This situation can occur e.g. when highlighting a block of code in an editor and formatting only that block.
+(Indeed, both LanguageServer.jl and JETLS.jl support this feature.)
+
+It is also useful for minimising diffs: by formatting only the lines that have been newly changed, you can avoid introducing formatting-only diffs in other parts of a file.
+
+Since version 2.7, JuliaFormatter allows you to do this with the `lines` keyword argument in `format_text(...; lines=[(start_line, end_line)], ...)`.
+Multiple ranges can be specified; each range must be a tuple of two (1-indexed) integers representing the start and end line of the range to format.
+
+```@example lines
+s = """
+f(a      , g(b      ,
+    h(  12  ),
+))"""
+
+# Format only line 2.
+using JuliaFormatter
+format_text(s; lines=[(2, 2)]) |> println
+```
+
+The second line (`h(12)`) is now formatted, but the extra spaces in the first line have not been collapsed.
+
+With the `jlfmt` CLI, you can specify `--lines=2:2` to achieve the same effect.
+
+Note, however, that this works best when the lines to be formatted are a self-contained block of code.
+This is because formatting is context-sensitive: it's not possible to format a single line in isolation without considering where it occurs!
+
+This can sometimes lead to odd results, and indeed the example above was chosen to showcase this.
+**In general, formatting of partial expressions is performed only on a best-effort basis.**
+For example:
+
+```@example lines
+# Format only line 2, but with a smaller margin.
+format_text(s; lines=[(2, 2)], margin=10) |> println
+```
+
+Here, the formatter decided to indent the call `h(12)` by eight spaces, even though based on its position in the file it should have been indented by only four spaces.
+Furthermore, as a result of this increased indentation, the formatter also decided to break up `h(12)` into multiple lines, even though `h(12),` with a four-space indent would have fit within the margin.
+
+To understand why, we need to look at what would happen if *all* the text were to be formatted:
+
+```@example lines
+format_text(s; margin=10) |> println
+```
+
+Because of the small margin, JuliaFormatter decided to break the calls to `f` and `g`, meaning that `h(12)` would now get two levels of indentation.
+When formatting only line 2, however, you don't see the changes to the surrounding code: the only visible change is that of `h(12)`.
+
+## A note about other special comments
+
+Note that any comment that begins with `#! __JuliaFormatter` is reserved for internal use.
+For example, the option to format only specific lines of a file uses such marker comments.
+If you have one of these in your source code, unexpected results may occur.
+
+It is very unlikely that your source code will inadvertently include such a comment, but this is documented here for completeness!

src/JuliaFormatter.jl

@@ -152,6 +152,7 @@ include("nest_utils.jl")
 include("print.jl")
 include("markdown.jl")
 include("copied_from_documenter.jl")
+include("line_ranges.jl")
 
 const UNIX_TO_WINDOWS = r"\r?\n" => "\r\n"
 const WINDOWS_TO_UNIX = "\r\n" => "\n"
@@ -168,30 +169,58 @@ normalize_line_ending(s::AbstractString, replacer = WINDOWS_TO_UNIX) = replace(s
         style::AbstractStyle = DefaultStyle(),
         indent::Int = 4,
         margin::Int = 92,
+        lines::Union{Nothing,Vector{Tuple{Int,Int}}} = nothing,
         options...,
     )::String
 
 Formats a Julia source passed in as a string, returning the formatted
 code as another string.
 
 See [Formatting Options](@ref formatting-options) for details on available options.
+
+# Line-range formatting
+
+Pass `lines` to restrict formatting to a set of line ranges, emitting everything else
+verbatim. `lines` is a `Vector{Tuple{Int,Int}}` of inclusive, 1-based `(start, stop)` line
+ranges, e.g. `format_text(text; lines = [(1, 10), (42, 47)])`. Overlapping and adjacent
+ranges are merged. A range that begins or ends in the middle of a multi-line expression is
+formatted on a best-effort basis.
 """
 function format_text(text::AbstractString; style::AbstractStyle = DefaultStyle(), kwargs...)
     return format_text(text, style; kwargs...)
 end
 
-function format_text(text::AbstractString, style::AbstractStyle; kwargs...)
+function format_text(
+    text::AbstractString,
+    style::AbstractStyle;
+    lines::Union{Nothing,Vector{Tuple{Int,Int}}} = nothing,
+    kwargs...,
+)
     if isempty(text)
         return text
     end
+    if lines !== nothing
+        # Restrict formatting to the given line ranges (see `line_ranges.jl`). This re-enters
+        # `format_text` without `lines` for the actual formatting, so it works for any style.
+        return format_line_ranges(text, style, lines; kwargs...)
+    end
     opts = Options(; merge(options(style), kwargs)...)
     return format_text(text, style, opts)
 end
 
-function format_text(text::AbstractString, style::SciMLStyle; maxiters = 3, kwargs...)
+function format_text(
+    text::AbstractString,
+    style::SciMLStyle;
+    maxiters = 3,
+    lines::Union{Nothing,Vector{Tuple{Int,Int}}} = nothing,
+    kwargs...,
+)
     if isempty(text)
         return text
     end
+    if lines !== nothing
+        return format_line_ranges(text, style, lines; maxiters, kwargs...)
+    end
     opts = Options(; merge(options(style), kwargs)...)
     # We need to iterate to a fixpoint because the result of short to long
     # form isn't properly formatted
@@ -309,7 +338,7 @@ function _format_file(
     format_markdown::Bool = false,
     format_options...,
 )::Bool
-    path, ext = splitext(filename)
+    _, ext = splitext(filename)
     shebang_pattern = r"^#!\s*/.*\bjulia[0-9.-]*\b"
     formatted_str = if match(r"^\.[jq]*md$", ext) ≠ nothing
         if !(format_markdown)