feat(lua): vim.fs.slug() #41005

Problem:
Several subsystems need to derive a short, filesystem-safe identifier from an
arbitrary path, and each reinvents it ad-hoc:
- `'undodir'` and `swapfiles` encode the full path into a single filename, which
  may exceed filesystem length-limits.
- `:connect ssh://` needs the SSH ControlPath socket name to stay under the
  104-byte `sun_path` limit on macOS; today the path overflows it.
- the upcoming :terminal state dir.
- arbitrary plugin purposes.

Solution:
Provide `vim.fs.slug()`, which generates a bounded, one-way filename from an
arbitrary string. The input is normalized so equivalent paths produce the
same result. An 8-char hash is appended for uniqueness

1 files changed, 42 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 058a1dc4f2..2a26270a83 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2951,6 +2951,48 @@ vim.fs.root({source}, {marker})                                *vim.fs.root()*
         (`string?`) Directory path containing one of the given markers, or nil
         if no directory was found.
 
+vim.fs.slug({path}, {opts})                                    *vim.fs.slug()*
+    Generates a bounded, filesystem-safe filename from an arbitrary identity
+    string.
+    • The input is normalized via |vim.fs.normalize()| so that equivalent
+      paths produce the same result (e.g., `~/foo` and `/home/username/foo`).
+    • `$HOME` is replaced with `~`. On Windows, UNC paths are replaced with
+      `=unc-`.
+    • An 8-character hex hash (|sha256()|) of the normalized input is appended
+      to prevent collisions.
+    • Unsafe characters (`/ \ : * ? " < > |`, whitespace, control characters)
+      are replaced with `-`, and trailing `-` and `.` are stripped.
+    • If `opts.maxlen` is exceeded, the result will be truncated to
+      `{head}~~~{tail}-{hash8}`.
+    • If the sanitized name is empty, the reserved label `=special` will be
+      used.
+
+    Examples: >lua
+        vim.fs.slug('/tmp/test/foo.md')
+           --> "tmp-test-foo.md-{hash}"
+
+        vim.fs.slug('C:/src/project/main.c')
+           --> "C--src-project-main.c-{hash}"
+
+        vim.fs.slug(('/a/very/long/path'):rep(10) .. '/file.txt', { maxlen = 60 })
+           --> "a-very-long-~~~-path-a-very-long-path-file.txt-{hash}"
+
+        vim.fs.slug('home/username/file.txt')
+           --> "~-file.txt-{hash}"
+<
+
+    Attributes: ~
+        Since: 0.13.0
+
+    Parameters: ~
+      • {path}  (`string`) a string that is not filesystem-safe.
+      • {opts}  (`table?`) Optional parameters:
+                • maxlen: (integer) Max byte length of the result. Default is
+                  180. Value must be at least 8.
+
+    Return: ~
+        (`string`) Filesystem-safe file name
+
 
 ==============================================================================
 Lua module: vim.glob                                                *vim.glob*