LuaForQC — Lua IDE for QC Games (青瓷游戏)

基于 LuaHelper 二次开发，专为青瓷游戏团队打造的 Lua 语言工具。 在原版高性能 LSP 基础上，新增 class/module/enum 支持、访问控制、废弃声明诊断、正则诊断忽略和大型工程增量分析优化等特性。

✨ 本插件独有特性（相比原版 LuaHelper 的增强）

1. Lua 5.1 module(...) 模块声明支持

• 背景：本插件基于 LuaHelper 二次开发，补充了 Lua 5.1 中 module(...) 的模块声明支持，方便兼容现有项目。
• 作用：为使用 module('modname', package.seeall) 的代码提供模块内符号解析、跳转、补全、引用与诊断。
• 识别规则：
  • 识别 module("xxx", package.seeall)，将当前文件声明的符号归入全局模块 xxx 的命名空间；

示例：

-- a.lua
module("A", package.seeall)

function foo(x)
	return x + 1
end

BAR = 42

-- b.lua
A.foo(1)
print(A.BAR)

注意：

• 新项目建议使用“返回表”模块风格（return table），module(...) 支持主要用于兼容旧项目；

2. 忽略不存在的全局变量（支持正则）

• 配置项：luahelper.base.ignoreUndefinedGlobals（字符串数组）
• 规则：同一数组中可混合“精确名”和“正则”
  • 精确名：直接写变量名，如 "GlobalConfig"、"DEV"
  • 正则：两种写法任选其一
    • 前缀：regex:^cc.
    • 斜杠：/^cc./

示例 settings.json 片段：

{
	"luahelper.base.ignoreUndefinedGlobals": [
		"GlobalConfig",
		"__DEV__",
		"regex:^cc\\.",
		"/^GAME_/"
	]
}

说明：精确项性能更好（哈希匹配）；正则仅对显式声明的项编译与匹配。上述配置会忽略如 cc.Sprite、GAME_VERSION 等前缀匹配的未定义全局告警。

3. class(...) 的 super 继承与隐式声明支持

• 继承：当使用 class 函数配合父类时，支持从父类（super）继承字段与方法信息，悬停/补全/跳转均可透传展示。
• 隐式声明：未显式 ---@class 时，可基于 class('Name') 与后续成员赋值推断类型，提供基本的类型感知与诊断。

示例：

Animal = class("Animal")
function Animal:say() end

Dog = class("Dog", Animal) -- 此处不需要显式添加注解
function Dog:init()
    self:say();	-- 从 super 继承的方法，可补全/跳转
end

4. 类成员/属性访问控制修饰符支持 (@private, @protected, @public)

• 背景：为类属性和类方法引入标准的 OOP（面向对象）访问修饰符，便于在大型 Lua 项目中支持更严格、更清晰的作用域和信息封装。
• 作用：
  • 静态语义诊断：支持对类属性的点语法访问以及类方法的冒号语法调用进行访问级别（Visibility）的安全审计。一旦有非授权的代码上下文跨越可见性边界（比如外部文件违规访问 @private/@protected），编辑器会实时下划线警告。
  • 智能补全过滤：自动提示与自动补全时，该过滤机制会与可见性权限无缝联动。如果没有合法的访问权限（如在外部类或外部文件中调取 private / protected 成员），补全列表会自动将其屏蔽隐藏，只展示合规的公有成员。
• 可见性修饰规则：
  • private（私有）：只有在当前类（同名 Class）的上下文中可访问。
  • protected（保护）：在同一文件、当前类定义文件，或通过继承自当前类的子类对象/子类上下文中可以访问。
  • public（公开，缺省默认值）：公开可见，任何地方均可被补全和调用。

示例：

-- base.lua
---@class Base
---@field public publicField number
---@field protected protectedField number
---@field private privateField number
local Base = {}

---@private
function Base:privateMethod() end


-- external.lua
local Base = require("base")
---@type Base
local externalObj = Base

externalObj.publicField = 100     -- 允许 (public)
externalObj.protectedField = 200  -- 报错 (protected, 外部上下文违规访问)
externalObj.privateField = 300    -- 报错 (private, 外部上下文违规访问)
externalObj:privateMethod()       -- 报错 (private 函数, 外部上下文违规调用)

5. 废弃声明支持 (@deprecated)

• 使用 ---@deprecated 标记不再推荐使用的变量、成员、方法或模块符号，可在注解后附带迁移原因或替代建议。
• 引用废弃声明时会显示警告诊断，并使用 VS Code 标准 deprecated tag 标记对应位置。
• 代码补全、补全详情、Hover、文档符号和工程符号会同步展示废弃状态及原因。
• 可通过 luahelper.Warn.CheckDeprecated 控制是否报告废弃声明的使用位置。

示例：

local API = {}

---@deprecated 请改用 API.newMethod
function API.oldMethod()
end

function API.newMethod()
end

API.oldMethod() -- 显示废弃警告和替代建议

6. 命名枚举支持 (@enum)

• 使用 ---@enum TypeName 声明枚举类型，枚举成员会保留独立的名义类型，不会与裸数字、字符串或其他枚举自动混用。
• 支持普通 table 和项目常用的 createEnum({ ... }) 写法。
• 支持枚举成员补全、Hover、定义跳转、文件符号，以及参数、赋值、局部变量初始化和返回值类型检查。
• 旧的 ---@enum start / ---@enum end 已移除。

示例：

---@enum Color
local Color = {
    Red = 1,
    Green = 2,
    Blue = 3,
}

---@param color Color
local function setColor(color)
end

setColor(Color.Red) -- 正确
setColor(1)         -- 类型错误

📖 基础功能（继承自 LuaHelper）

本插件继承了 LuaHelper 的全部核心能力：

详细使用说明请参考 LuaHelper 官方文档。

⚡ v0.3.3 性能与稳定性优化

• LSP 请求锁从互斥锁升级为读写锁，Hover/Define/Complete 等只读请求改为并发读锁
• 保存链路与文件监控缩小写锁临界区，减少"正在加载"现象
• 保存时根据全局符号、文件引用和注解类型依赖，仅重新分析真正受影响的文件
• 第三阶段全局符号按变化名称局部聚合，减少大型工程中的重复重建与临时分配
• 语法错误期间保留最近一次成功语义，恢复后自动替换，减少补全和诊断结果抖动

📦 安装

• 打开 VS Code 扩展市场
• 搜索 LuaForQC
• 点击安装

🙏 致谢

• 原始项目：LuaHelper by Tencent
• 调试组件：LuaPanda
• 格式化引擎：EmmyLuaCodeStyle
• AST 支持：luago-book
• 注解系统参考：EmmyLua

📄 License

BSD-3-Clause