[200_46] 打包流程纳入 tests 目录并在打包前生成 doc 索引

.github/workflows/package.yml

@@ -10,7 +10,6 @@ on:
   push:
     tags:
       - '*'
-
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -80,6 +79,9 @@ jobs:
         xmake config -vyD --policies=build.ccache -o tmp/build -m releasedbg --repl=true
         xmake build goldfish
 
+    - name: Build function doc index
+      run: ./bin/gf doc --build-json
+
     - name: Package
       run: xmake pack -vyD goldfish
 
@@ -181,6 +183,10 @@ jobs:
         xmake config -vyD -o tmp/build -m release --repl=true --yes
         xmake build goldfish
 
+    - name: Build function doc index
+      shell: pwsh
+      run: .\bin\gf.exe doc --build-json
+
     - name: Package
       run: xmake pack -vyD goldfish
 

devel/200_46.md

@@ -0,0 +1,173 @@
+# [200_46] 打包流程纳入 tests 目录并在打包前生成 doc 索引
+
+## 任务相关的代码文件
+- `xmake.lua`
+- `.github/workflows/package.yml`
+- `devel/200_46.md`
+
+## 如何测试
+```bash
+# 1. 构建当前 gf
+xmake config -o tmp/build -m releasedbg --repl=true --yes
+xmake build goldfish
+
+# 2. 在源码树生成函数索引
+./bin/gf doc --build-json
+
+# 3. 做一次本地 staging 安装
+rm -rf /tmp/goldfish-stage
+xmake install -o /tmp/goldfish-stage goldfish
+
+# 4. 验证 tests 与 function-library-index.json 已进入安装目录
+ls -l /tmp/goldfish-stage/share/goldfish/tests/function-library-index.json
+find /tmp/goldfish-stage/share/goldfish/tests -maxdepth 2 -type f | head
+
+# 5. 验证安装态 gf doc 可以直接读取文档
+/tmp/goldfish-stage/bin/gf doc "string-split"
+/tmp/goldfish-stage/bin/gf doc "alist->fxmapping/combinator"
+```
+
+## 2026-03-31 打包前自动生成 function-library-index.json，并将 tests/ 一起打包
+
+### What
+
+本次改动有两部分：
+
+1. 在自动打包流程里，`xmake pack` 之前先执行 `gf doc --build-json`
+2. 将 `tests/` 整个目录纳入最终安装包与 source package
+
+### Why
+
+随着 `gf doc` 功能逐步完善，安装态已经不只是需要：
+
+1. `share/goldfish` 下的标准库
+2. `share/goldfish/tools/...` 下的子命令模块
+
+还需要额外的数据文件：
+
+1. `tests/` 下的测试文档本体
+2. `tests/function-library-index.json`
+
+原因是：
+
+1. `gf doc` 的文档内容直接来自 `tests/<group>/<library>/...`
+2. `gf doc FUNC` 与模糊匹配依赖 `function-library-index.json`
+
+如果最终安装包里没有 `tests/`，那么即使：
+
+1. `golddoc` 模块已经被安装
+2. `doc` 子命令入口也已经存在
+
+安装态的 `gf doc` 仍然无法真正工作。
+
+### How
+
+#### 1. 在 package workflow 中先生成索引
+
+修改了：
+
+1. `.github/workflows/package.yml`
+
+在 Linux 与 Windows 的打包 job 中，都在：
+
+1. `xmake build goldfish`
+2. `xmake pack -vyD goldfish`
+
+之间新增了一步：
+
+```bash
+gf doc --build-json
+```
+
+对应地：
+
+1. Linux job 使用 `./bin/gf doc --build-json`
+2. Windows job 使用 `.\bin\gf.exe doc --build-json`
+
+这样可以保证：
+
+1. `function-library-index.json` 在 pack 发生前已经存在
+2. 打包出来的产物携带的是最新索引
+
+#### 2. 在 xmake 安装内容里加入 tests
+
+修改了：
+
+1. `xmake.lua`
+
+在 `target("goldfish")` 的安装文件列表中新增：
+
+1. `add_installfiles("$(projectdir)/(tests/**)", {prefixdir = "share/goldfish"})`
+
+这会把源码树中的：
+
+1. `tests/liii/**`
+2. `tests/scheme/**`
+3. `tests/resources/**`
+4. `tests/function-library-index.json`
+
+统一安装到：
+
+1. `share/goldfish/tests/...`
+
+这个布局和当前运行时逻辑是匹配的，因为 `golddoc` 会从当前 `*load-path*` 推导关联的 `tests` 根目录。
+
+#### 3. source package 也补入 tests
+
+除了安装态文件列表外，还在 `xpack("goldfish")` 的 source files 列表中新增：
+
+1. `add_sourcefiles("(tests/**)")`
+
+这样 source package 也不会漏掉：
+
+1. 测试文档
+2. 资源文件
+3. 生成的函数索引
+
+### 影响
+
+这次改动最大的实际效果是：
+
+1. 安装后的 `gf doc` 不再只在源码树里可用
+2. 安装包里的 `gf doc FUNC`、模糊匹配和库文档查询都具备所需的数据基础
+
+顺带也让：
+
+1. `share/goldfish/tests/resources`
+
+这类测试依赖资源一起进入安装目录，为后续如果希望在安装态做更多测试或诊断留出了空间。
+
+### 验证结果
+
+本次改动已实际验证：
+
+1. `./bin/gf doc --build-json`
+   - 成功生成 `tests/function-library-index.json`
+
+2. `xmake install -o /tmp/goldfish-stage goldfish`
+   - 成功完成 staging 安装
+
+3. `/tmp/goldfish-stage/share/goldfish/tests/function-library-index.json`
+   - 文件存在
+
+4. `/tmp/goldfish-stage/share/goldfish/tests/...`
+   - 已包含 `liii`、`scheme`、`resources` 等测试文件
+
+5. `/tmp/goldfish-stage/bin/gf doc "string-split"`
+   - 安装态可直接输出对应文档
+
+6. `/tmp/goldfish-stage/bin/gf doc "alist->fxmapping/combinator"`
+   - 安装态可直接输出对应文档
+
+### 备注
+
+这次改动优先保证“打包结果可用”，因此采用的是最直接的链路：
+
+1. workflow 显式执行 `gf doc --build-json`
+2. `xmake.lua` 显式安装 `tests/**`
+
+后续如果需要进一步收敛实现，可以再评估是否把：
+
+1. 索引生成
+
+下沉到更靠近 `xpack` 的 hook 中，减少 workflow 中的显式命令步骤。

xmake.lua

@@ -162,6 +162,7 @@ target ("goldfish") do
     add_installfiles("$(projectdir)/tools/goldfix/(liii/*.scm)", {prefixdir = "share/goldfish/tools/goldfix"})
     add_installfiles("$(projectdir)/tools/goldtest/liii/goldtest.scm", {prefixdir = "share/goldfish/tools/goldtest/liii"})
     add_installfiles("$(projectdir)/tools/golddoc/(liii/*.scm)", {prefixdir = "share/goldfish/tools/golddoc"})
+    add_installfiles("$(projectdir)/(tests/**)", {prefixdir = "share/goldfish"})
 end
 
 if is_plat("wasm") then
@@ -216,6 +217,7 @@ xpack ("goldfish")
     add_sourcefiles("xmake.lua")
     add_sourcefiles("(src/**)")
     add_sourcefiles("(goldfish/**)")
+    add_sourcefiles("(tests/**)")
     add_sourcefiles("(tools/**)")
     add_sourcefiles("(3rdparty/**)")
     on_load(function (package)