LuaLS / LuaLS/lua-language-server

Add `upvalue` semantic token modifier

未關閉
#3,456 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

主要語言
Lua
星號
4.4k
分支
442
PR 合併指標
30 天內沒有已合併 PR

描述

LuaLS should expose whether a `variable` reference is an upvalue through a new `upvalue` semantic token modifier.

Currently, local variables and upvalues are both reported as:

```text
semantic token type: variable
modifiers: -
```

while globals are already distinguished using:

```text
semantic token type: variable
modifiers: global
```

This makes it impossible for editors such as VS Code to visually distinguish local variables from upvalues.

## Example

```lua
local function outer()
local value = 123

return function()
print(value) -- upvalue
end
end
```

Currently the `value` reference inside the inner function is:

```text
variable
```

It would be useful for LuaLS to report it as:

```text
variable + upvalue
```

while the declaration remains:

```text
variable
```

## Proposed semantic token model

```text
variable -> local variable
variable + upvalue -> upvalue
variable + global -> global variable
parameter -> function parameter
```

For example:

```lua
local foo = 1

local function outer(bar)
local baz = 2

return function(qux)
print(foo) -- upvalue
print(bar) -- upvalue
print(baz) -- upvalue
print(qux) -- parameter
print(print) -- global
end
end
```

would produce approximately:

```text
foo -> variable + upvalue
bar -> variable + upvalue
baz -> variable + upvalue
qux -> parameter
print -> variable + global
```

Ordinary locals would remain simply:

```text
variable
```

## Why a modifier?

A modifier seems preferable to introducing a new semantic token type because `upvalue` describes a property of a variable reference rather than a fundamentally different kind of symbol.

It also fits the existing LuaLS representation of globals:

```text
variable + global
```

This gives editor themes a simple way to distinguish all four cases:

```text
variable
variable + upvalue
variable + global
parameter
```

## Scope

The `upvalue` modifier should be applied to references resolved to a variable declared in an enclosing lexical scope.

For example:

```lua
local x = 1

local function f()
print(x)
end
```

would be:

```text
x declaration -> variable
x reference -> variable + upvalue
```

Nested closures should work recursively.

## Motivation

This would allow VS Code themes to use different colors for locals, parameters, upvalues, and globals, making lexical scope much easier to understand in closure-heavy Lua/LuaJIT code.

LuaLS already performs the necessary lexical-scope resolution; this proposal would expose that information through semantic tokens.

貢獻指南

開啟貢獻指南

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

研究方向

Issue 沒有指出任何檔案或測試。首先定位 LuaLS 的語意 token 產生,以及用於變數參照的詞法作用域解析;追蹤現有 global modifier 的指派方式。完成的標準是:解析到外層作用域變數的參照會取得 upvalue modifier,宣告和一般區域變數維持不變,並且巢狀 closure 有測試涵蓋。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
lua
領域
devtools
Issue 類型
功能
難度
4/5
預估耗時
3-5 天
活躍度
活躍
描述清晰度
基本清楚
新手友好度
52/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。