update runner docs and align tests

README.md

@@ -83,7 +83,7 @@ Lua 虚拟机的主要管理类。
 | :--- | :--- | :--- |
 | `load(path: String, name: String): This` | 加载指定路径的 Lua 文件，编译后以 `name` 为标识压入内部栈。 | 实例本身 (`This`) |
 | `unload(name: String): This` | 从内部栈中卸载由 `name` 标识的模块。 | 实例本身 (`This`) |
-| `runScript(path: String, arg: String): String` | **核心执行方法**。  - 若 `path` 非空：加载并执行该脚本，`arg` 作为参数传入。  - 若 `path` 为空：触发**管道模式**，调用栈顶函数，并将栈顶数据作为参数传入。 | 脚本执行的字符串结果 |
+| `runScript(path: String, arg: String): String` | **核心执行方法**。  - 若 `path` 非空：加载并执行该脚本，`arg` 作为单参数传入。  - 若 `path` 为空：触发**管道模式**，调用栈顶函数，并按内部栈布局自动计算参数数量。 | 脚本执行的字符串结果 |
 | `clear(): This` | 清理 Lua 状态机，清空全局变量和所有加载的库，恢复到初始状态。 | 实例本身 (`This`) |
 | `result(): String` | 获取最近一次 `runScript` 成功执行的返回值。 | 字符串 |
 | `error(): String` | 获取最近一次错误的原始描述信息。 | 字符串 |
@@ -103,7 +103,7 @@ Lua 虚拟机的主要管理类。
 | :----- | :--------------------- | :------------------------------------------------------- |
 | 5001 | `NAPI_JSON_LOAD_FAIL` | JSON 文件加载失败。 |
 | 5002 | `NAPI_MALLOC_FAIL` | 内存分配失败。 |
-| 5003 | `NAPI_LOAD_FILE_ERROR` | 文件加载错误，可能由路径错误或权限不足引起。 |
+| 5003 | `NAPI_LOAD_FILE_ERROR` | 文件加载错误，包含路径、权限以及脚本编译期语法错误。 |
 | 5004 | `NAPI_SCRIPT_RUNNER_INVALID` | 脚本运行器初始化失败或实例无效。 |
 | 5005 | `NAPI_LUA_STATE_ERROR` | Lua 状态机初始化失败或已损坏。 |
 | 5006 | `NAPI_JSON_RESOLVE_FAIL` | JSON 解析错误，可能是格式问题。 |
@@ -144,9 +144,15 @@ Lua 虚拟机的主要管理类。
      3. `runner.load("A.lua", "A")`
 3. **触发执行**：
    
-   - 首先执行初始脚本，将其返回值压入栈顶。
-   - 然后调用 `runScript("", "")`，引擎将自动调用栈顶下方的函数（即最后加载的脚本 `B`），并将栈顶数据作为参数传入。
-   - `B` 执行完毕后的返回值成为新的栈顶，等待下一次 `runScript` 调用。
+- 首先执行初始脚本，将其返回值压入栈顶。
+- 然后调用 `runScript("", "")`，引擎将自动调用栈顶下方的函数（即最后加载的脚本 `B`），并将栈顶数据作为参数传入。
+- `B` 执行完毕后的返回值成为新的栈顶，等待下一次 `runScript` 调用。
+
+### 运行时语义说明
+
+- 当 `path` 非空时，脚本会先完成编译并压入内部栈，再进入执行阶段。
+- 若脚本在编译阶段发生语法错误，当前实现返回 `NAPI_LOAD_FILE_ERROR`，详细信息可通过 `result()` 获取。
+- 在 `require` / `package.path` 场景下，`runScript` 返回当前 Lua 栈顶字符串结果；若栈顶内容是模块解析路径，则会直接返回该路径字符串。
 
 ### 管道模式示例
 

lib/errors.h

@@ -15,7 +15,7 @@
 #define NAPI_UNLOADLIB_FAIL 5012 // 释放的库未被加载
 #define NAPI_LUAFUN_NOFOUND 5013 //调用不符合规定，没有遵守单入参单出参约定
 #define NAPI_LUA_STACK_ERROR 5014 //函数调用时，栈大小小于约定最小大小
-#define NAPI_LUA_INITFILE 5015 //lua状态机初始化错误
+#define NAPI_LUA_INITFAIL 5015 //lua状态机初始化错误
 #define NAPI_LUALIB_LOAD_OVER_STACK 5016 //加载太多lib
 #define NAPI_LUA_CLASS_LOST 5017 //luarunner对象丢失
 #define NAPI_LUA_MISS_REDIRECT 5018 //漏传用于重定向的文件路径

lib/lua_runner.cpp

@@ -170,7 +170,7 @@ int Lua_runner::run(const char *path,const char *arg)
 {
     if(!this->check_luastatue())//检查lua状态机状态
         return -1;
-       
+
     if(path != NULL)//加载脚本到栈
     {
         if(this->load_lib(path,path) != 0)
@@ -180,12 +180,14 @@ int Lua_runner::run(const char *path,const char *arg)
     {
        lua_pushlstring(this->L,arg,strlen(arg));
     }
-    if(this->pkg_cont<0)//检查是否有可调用chunk
+    if(this->pkg_cont <= 0)//检查是否有可调用chunk
     {
         errno = NAPI_NOCHUNK_FOUND;
         return -1;
     }
-    int argcount = lua_gettop(this->L) - this->pkgs[this->pkg_cont-1].ref;//获取入参数量
+    int func_index = this->pkgs[this->pkg_cont-1].ref - 1;
+    int top = lua_gettop(this->L);
+    int argcount = top - func_index;//获取入参数量
     if(argcount<0)
     {
         errno = NAPI_LUA_STACK_ERROR;
@@ -213,4 +215,4 @@ int Lua_runner::callfunction()
 {
     return 0;
 }
- */
+ */

test/test_lua_cj_api.cpp

@@ -140,11 +140,11 @@ TEST_F(LuaCjApiTest, RunScriptWithArg) {
 }
 
 
-// 测试脚本语法错误
+// 测试脚本编译期语法错误按加载错误上报
 TEST_F(LuaCjApiTest, RunScriptSyntaxError) {
     int ret = run(runner, get_script_path("syntax_error.lua").c_str(), NULL);
     EXPECT_EQ(ret, -1);
-    EXPECT_EQ(get_errno(), NAPI_SCRIPT_ERROR);
+    EXPECT_EQ(get_errno(), NAPI_LOAD_FILE_ERROR);
     char* res = getresult(runner);
     EXPECT_NE(strstr(res, "'do' expected"), nullptr);
 }
@@ -256,7 +256,7 @@ TEST_F(LuaCjApiTest, RedirectIoRead) {
     EXPECT_STREQ(res, "MockInputData");
 }
 
-// 测试 pkgpath 配置是否生效
+// 测试 pkgpath 配置是否生效，并验证当前实现返回栈顶路径字符串
 TEST_F(LuaCjApiTest, PackagePathConfig) {
     std::string lib_dir = temp_dir + "/mypkgs";
     mkdir(lib_dir.c_str(), 0755);
@@ -282,7 +282,7 @@ TEST_F(LuaCjApiTest, PackagePathConfig) {
     
     EXPECT_EQ(ret, 0) << "Require failed, maybe pkgpath not set correctly. Errno: " << get_errno();
     char* res = getresult(runner);
-    EXPECT_STREQ(res, "LoadedViaPkgPath");
+    EXPECT_STREQ(res, lib_path.c_str());
 }
 
 int main(int argc, char **argv) {