refactor(lua): rename vim.diff => vim.text.diff #34864

Problem:
`vim.diff()` was introduced before we had the `vim.text` module, where
it obviously belongs.

Solution:
Move it.

runtime/lua/vim/_editor.lua

@@ -1314,9 +1314,12 @@ end
 
 require('vim._options')
 
--- Remove at Nvim 1.0
+--- Remove at Nvim 1.0
 ---@deprecated
 vim.loop = vim.uv
+--- Renamed to `vim.text.diff`, remove at Nvim 1.0
+---@deprecated
+vim.diff = vim._diff ---@type fun(a: string, b: string, opts?: vim.text.diff.Opts): string|integer[][]?
 
 -- Deprecated. Remove at Nvim 2.0
 vim.highlight = vim._defer_deprecated_module('vim.highlight', 'vim.hl')

runtime/lua/vim/_meta/diff.lua

@@ -1,71 +0,0 @@
----@meta
-
---- Optional parameters:
---- @class vim.diff.Opts
---- @inlinedoc
----
---- Invoked for each hunk in the diff. Return a negative number
---- to cancel the callback for any remaining hunks.
---- Arguments:
----   - `start_a` (`integer`): Start line of hunk in {a}.
----   - `count_a` (`integer`): Hunk size in {a}.
----   - `start_b` (`integer`): Start line of hunk in {b}.
----   - `count_b` (`integer`): Hunk size in {b}.
---- @field on_hunk? fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer?
----
---- Form of the returned diff:
----   - `unified`: String in unified format.
----   - `indices`: Array of hunk locations.
---- Note: This option is ignored if `on_hunk` is used.
---- (default: `'unified'`)
---- @field result_type? 'unified'|'indices'
----
---- Run linematch on the resulting hunks from xdiff. When integer, only hunks
---- upto this size in lines are run through linematch.
---- Requires `result_type = indices`, ignored otherwise.
---- @field linematch? boolean|integer
----
---- Diff algorithm to use. Values:
----   - `myers`: the default algorithm
----   - `minimal`: spend extra time to generate the smallest possible diff
----   - `patience`: patience diff algorithm
----   - `histogram`: histogram diff algorithm
---- (default: `'myers'`)
---- @field algorithm? 'myers'|'minimal'|'patience'|'histogram'
---- @field ctxlen? integer Context length
---- @field interhunkctxlen? integer Inter hunk context length
---- @field ignore_whitespace? boolean Ignore whitespace
---- @field ignore_whitespace_change? boolean Ignore whitespace change
---- @field ignore_whitespace_change_at_eol? boolean Ignore whitespace change at end-of-line.
---- @field ignore_cr_at_eol? boolean Ignore carriage return at end-of-line
---- @field ignore_blank_lines? boolean Ignore blank lines
---- @field indent_heuristic? boolean Use the indent heuristic for the internal diff library.
-
--- luacheck: no unused args
-
---- Run diff on strings {a} and {b}. Any indices returned by this function,
---- either directly or via callback arguments, are 1-based.
----
---- Examples:
----
---- ```lua
---- vim.diff('a\n', 'b\nc\n')
---- -- =>
---- -- @@ -1 +1,2 @@
---- -- -a
---- -- +b
---- -- +c
----
---- vim.diff('a\n', 'b\nc\n', {result_type = 'indices'})
---- -- =>
---- -- {
---- --   {1, 1, 1, 2}
---- -- }
---- ```
----
----@param a string First string to compare
----@param b string Second string to compare
----@param opts? vim.diff.Opts
----@return string|integer[][]?
----     See {opts.result_type}. `nil` if {opts.on_hunk} is given.
-function vim.diff(a, b, opts) end

runtime/lua/vim/text.lua

@@ -2,6 +2,80 @@
 
 local M = {}
 
+--- Optional parameters:
+--- @class vim.text.diff.Opts
+--- @inlinedoc
+---
+--- Invoked for each hunk in the diff. Return a negative number
+--- to cancel the callback for any remaining hunks.
+--- Arguments:
+---   - `start_a` (`integer`): Start line of hunk in {a}.
+---   - `count_a` (`integer`): Hunk size in {a}.
+---   - `start_b` (`integer`): Start line of hunk in {b}.
+---   - `count_b` (`integer`): Hunk size in {b}.
+--- @field on_hunk? fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer?
+---
+--- Form of the returned diff:
+---   - `unified`: String in unified format.
+---   - `indices`: Array of hunk locations.
+--- Note: This option is ignored if `on_hunk` is used.
+--- (default: `'unified'`)
+--- @field result_type? 'unified'|'indices'
+---
+--- Run linematch on the resulting hunks from xdiff. When integer, only hunks
+--- upto this size in lines are run through linematch.
+--- Requires `result_type = indices`, ignored otherwise.
+--- @field linematch? boolean|integer
+---
+--- Diff algorithm to use. Values:
+---   - `myers`: the default algorithm
+---   - `minimal`: spend extra time to generate the smallest possible diff
+---   - `patience`: patience diff algorithm
+---   - `histogram`: histogram diff algorithm
+--- (default: `'myers'`)
+--- @field algorithm? 'myers'|'minimal'|'patience'|'histogram'
+--- @field ctxlen? integer Context length
+--- @field interhunkctxlen? integer Inter hunk context length
+--- @field ignore_whitespace? boolean Ignore whitespace
+--- @field ignore_whitespace_change? boolean Ignore whitespace change
+--- @field ignore_whitespace_change_at_eol? boolean Ignore whitespace change at end-of-line.
+--- @field ignore_cr_at_eol? boolean Ignore carriage return at end-of-line
+--- @field ignore_blank_lines? boolean Ignore blank lines
+--- @field indent_heuristic? boolean Use the indent heuristic for the internal diff library.
+
+-- luacheck: no unused args
+
+--- Run diff on strings {a} and {b}. Any indices returned by this function,
+--- either directly or via callback arguments, are 1-based.
+---
+--- Examples:
+---
+--- ```lua
+--- vim.text.diff('a\n', 'b\nc\n')
+--- -- =>
+--- -- @@ -1 +1,2 @@
+--- -- -a
+--- -- +b
+--- -- +c
+---
+--- vim.text.diff('a\n', 'b\nc\n', {result_type = 'indices'})
+--- -- =>
+--- -- {
+--- --   {1, 1, 1, 2}
+--- -- }
+--- ```
+---
+---@diagnostic disable-next-line: undefined-doc-param
+---@param a string First string to compare
+---@diagnostic disable-next-line: undefined-doc-param
+---@param b string Second string to compare
+---@diagnostic disable-next-line: undefined-doc-param
+---@param opts? vim.text.diff.Opts
+---@return string|integer[][]? # See {opts.result_type}. `nil` if {opts.on_hunk} is given.
+function M.diff(...)
+  return vim._diff(...)
+end
+
 local alphabet = '0123456789ABCDEF'
 local atoi = {} ---@type table<string, integer>
 local itoa = {} ---@type table<integer, string>