@follenfang/wowdoc 0.0.8 → 0.0.10

package/README.md

@@ -71,7 +71,7 @@ branch / Tag / version / Commit
 
 | Source | Products / channels |
 | --- | --- |
-| Blizzard UI source | Retail, PTR, PTR2, Beta, Classic, Classic PTR/Beta, Classic Era/PTR, Anniversary, Titan |
+| Blizzard UI source | Retail, PTR, PTR2, Beta, Classic, Classic PTR/Beta, Classic Era/PTR, Anniversary, Titan, Forever |
 | [ElvUI](https://github.com/tukui-org/ElvUI) | main, PTR |
 | [WeakAuras](https://github.com/WeakAuras/WeakAuras2) | main |
 | [NDui](https://github.com/siweia/NDui) | main, Classic, Era, Anniversary, Titan |
@@ -117,17 +117,28 @@ wowdoc diff `
 ```powershell
 wowdoc validate `
   --path D:\AddOns\MyAddon `
+  --toc MyAddon_Mainline.toc `
   --source wow-ui-source `
   --product retail `
   --ref latest
 ```
 
+With `--toc`, wowdoc validates only the ordered Lua/XML closure actually loaded by that TOC, including recursive XML `Script` and `Include` references. The JSON result includes every file's load order and sources, exact Tag and immutable Commit evidence, diagnostics, unresolved dynamic references, and static coverage counts. Omit `--toc` to retain the original recursive Lua scan.
+
+Validate several client TOCs together with a matrix file:
+
+```powershell
+wowdoc validate-matrix --config wowdoc.matrix.json
+```
+
+The matrix preserves each target result and merges API/event signatures, XML templates, Mixins, Frame types, TOC Interface evidence, target-only files, diagnostics, and unresolved items. A valid static result means no error was found by the covered checks; it is not a guarantee of perfect in-game behavior.
+
 Every successful reference identifies the source, product, requested ref, matching Tag when available, resolved Commit, repository path, line, excerpt, and content hash.
 
 ## Command map
 
 ```text
-Search      wowdoc query | explore | inspect | diff | validate
+Search      wowdoc query | explore | inspect | diff | validate | validate-matrix
 Sources     wowdoc source list | check | sync
 Indexes     wowdoc index build | refresh | status
 Health      wowdoc doctor

package/README.zh-CN.md

@@ -71,7 +71,7 @@ npm install -g @follenfang/wowdoc --foreground-scripts --verbose
 
 | 源码 | 产品 / 通道 |
 | --- | --- |
-| 暴雪 UI 源码 | Retail、PTR、PTR2、Beta、Classic、Classic PTR/Beta、Classic Era/PTR、Anniversary、Titan |
+| 暴雪 UI 源码 | Retail、PTR、PTR2、Beta、Classic、Classic PTR/Beta、Classic Era/PTR、Anniversary、Titan、Forever |
 | [ElvUI](https://github.com/tukui-org/ElvUI) | main、PTR |
 | [WeakAuras](https://github.com/WeakAuras/WeakAuras2) | main |
 | [NDui](https://github.com/siweia/NDui) | main、Classic、Era、Anniversary、Titan |
@@ -117,17 +117,28 @@ wowdoc diff `
 ```powershell
 wowdoc validate `
   --path D:\AddOns\MyAddon `
+  --toc MyAddon_Mainline.toc `
   --source wow-ui-source `
   --product retail `
   --ref latest
 ```
 
+传入 `--toc` 后，wowdoc 只验证该 TOC 实际加载的有序 Lua/XML 闭包，并递归处理 XML `Script` 与 `Include`。JSON 会返回文件加载顺序和来源、精确 Tag、不可变 Commit、诊断、动态未决项和静态覆盖计数。不传 `--toc` 时继续使用原有递归 Lua 扫描。
+
+多客户端可以通过矩阵配置一次验证：
+
+```powershell
+wowdoc validate-matrix --config wowdoc.matrix.json
+```
+
+矩阵保留每个目标的完整结果，并归并 API/事件签名、XML 模板、Mixin、Frame 类型、TOC Interface、各端独有文件、诊断和动态未决项。静态结果有效只表示已覆盖检查中未发现 error，不保证插件在游戏内完美运行。
+
 查询成功后会返回 source、product、用户请求的 ref、匹配到的 Tag、实际 Commit、仓库路径、行号、代码片段和内容哈希。
 
 ## 命令一览
 
 ```text
-检索       wowdoc query | explore | inspect | diff | validate
+检索       wowdoc query | explore | inspect | diff | validate | validate-matrix
 源码       wowdoc source list | check | sync
 索引       wowdoc index build | refresh | status
 检查       wowdoc doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@follenfang/wowdoc",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Auditable WoW UI source intelligence CLI for coding agents",
   "license": "MIT",
   "type": "module",
@@ -21,11 +21,11 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@follenfang/wowdoc-darwin-arm64": "0.0.8",
-    "@follenfang/wowdoc-darwin-x64": "0.0.8",
-    "@follenfang/wowdoc-linux-arm64": "0.0.8",
-    "@follenfang/wowdoc-linux-x64": "0.0.8",
-    "@follenfang/wowdoc-win32-x64": "0.0.8"
+    "@follenfang/wowdoc-darwin-arm64": "0.0.10",
+    "@follenfang/wowdoc-darwin-x64": "0.0.10",
+    "@follenfang/wowdoc-linux-arm64": "0.0.10",
+    "@follenfang/wowdoc-linux-x64": "0.0.10",
+    "@follenfang/wowdoc-win32-x64": "0.0.10"
   },
   "scripts": {
     "postinstall": "node scripts/install.mjs",

package/skill/SKILL.md

@@ -9,11 +9,12 @@ Translate the user's wording into explicit `source`, `product`, `ref`, `topic`,
 
 1. Run `wowdoc source list --source SOURCE --product PRODUCT` when source, product, or available versions are uncertain.
 2. Prefer an exact displayed plugin version. The CLI maps it only to an exact Tag and immutable Commit.
-3. Use one read command: `query` for a focused question, `explore` for a subsystem, `inspect` for a known symbol/path, `diff` for two versions, or `validate` for a local AddOn.
+3. Use one read command: `query` for a focused question, `explore` for a subsystem, `inspect` for a known symbol/path, `diff` for two versions, `validate --toc` for one client AddOn load closure, or `validate-matrix` for multiple client TOCs. Omit `--toc` only for the legacy recursive Lua scan.
 4. If the CLI returns `snapshot_not_ready`, run only the listed `source sync` and `index build|refresh` steps, then retry the original read command.
 5. If an exact plugin version returns `version_not_found`, keep the same source and product, run `source check`, synchronize and refresh if needed, then query `latest`. Mark the answer with `requestedVersion`, `matchedTag=null`, `resolutionMode=latest_fallback`, product branch, resolved Commit, and state that the evidence is from latest rather than the requested version.
 6. Do not apply latest fallback to `ambiguous_version`, `unsupported_build`, `ref_not_found`, or update failures.
 7. Cite `sourceId`, product, Tag when present, resolved Commit, path, line, and the returned excerpt. Treat `dynamic-unresolved` edges as unresolved, not exact.
+8. A successful static validation means the reported checks found no error. Never describe it as a guarantee that the AddOn runs perfectly in game.
 
 The data directory defaults to `~/.wowdoc`. `WOWDOC_HOME` may override it with another writable path for an isolated workspace, another drive, or a server deployment. This changes only wowdoc's source, index, object, lock, and log storage; it does not change the npm installation directory or the Skill directory. Run `wowdoc doctor` to see the resolved data directory.
 

package/skill/references/commands.md

@@ -6,7 +6,8 @@ wowdoc explore --source SOURCE --product PRODUCT --ref REF --topic TOPIC --text
 wowdoc inspect --source SOURCE --product PRODUCT --ref REF --symbol QUALIFIED_NAME
 wowdoc inspect --source SOURCE --product PRODUCT --ref REF --path REPOSITORY_PATH
 wowdoc diff    --source SOURCE --product PRODUCT --from REF --to REF
-wowdoc validate --path ADDON_DIR --source SOURCE --product PRODUCT --ref REF
+wowdoc validate --path ADDON_DIR --toc TOC_FILE --source SOURCE --product PRODUCT --ref REF
+wowdoc validate-matrix --config MATRIX_JSON
 wowdoc source list  --source SOURCE --product PRODUCT
 wowdoc source check --source SOURCE --product PRODUCT
 wowdoc source sync  --source SOURCE --product PRODUCT
@@ -24,6 +25,8 @@ wowdoc uninstall --yes
 
 Use exact qualified identifiers when known. For natural-language questions, select a topic and use the narrowest stable identifier, event, template, TOC field, asset path, or API name present in the question. Prefer results marked `exact_symbol`; verify relationship confidence and retain the returned excerpt as evidence.
 
+Use `validate --toc` when a client TOC is known. It limits checks to that TOC's ordered Lua/XML load closure. Use `validate-matrix` when the AddOn declares multiple client TOCs. Keep `unresolved` items unresolved, and describe `valid: true` as no error found by the reported static checks rather than proof of perfect in-game behavior. Omit `--toc` only when the caller intentionally wants the legacy recursive Lua scan.
+
 ## Data directory
 
 Without configuration, all source mirrors, objects, indexes, manifests, locks, logs, and temporary worktrees live under `~/.wowdoc`.

package/skill/references/source-catalog.md

@@ -6,9 +6,12 @@
 | `wow-ui-source` | `ptr`, `ptr2`, `beta` | matching channel | Channel is separate from build |
 | `wow-ui-source` | `classic`, `classic-ptr`, `classic-beta` | matching classic channel | Do not infer compatibility from branch name |
 | `wow-ui-source` | `classic-era`, `classic-era-ptr`, `anniversary`, `titan` | matching channel | Titan is its own product |
+| `wow-ui-source` | `forever` | `forever` | 1.60 line (e.g. `1.60.1`); do not infer compatibility from branch name |
 | `elvui` | `main`, `ptr` | matching branch | Version input such as `15.18` maps exactly to Tag `v15.18` |
 | `weakauras` | `main` | `main` | Current source supports its declared TOCs; check the selected snapshot |
 | `ndui` | `main`, `classic`, `era`, `anniversary`, `titan` | `master`, `Classic`, `Era`, `Anniversary`, `Titan` | Tags are filtered by product branch reachability and product-line rule |
 | `ellesmereui` | `main` | `main` | Retail-oriented suite; version input maps to `v` Tag |
 
 The version truth is `Tag -> Commit -> source snapshot`. Release attachments and packaged externals can differ from Tag source; describe evidence as Tag source, not an installed package reconstruction.
+
+Interface evidence for `validate` comes from the snapshot's build `version.txt` (e.g. `1.60.1` → `16001`) plus indexed TOC entries. A `toc_interface_mismatch` against a rebuilt snapshot means the declared Interface is genuinely absent from that build.