wow-secret-lint 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 1.3.0 - 2026-08-31
+
+Patch 12.1 ("Curse of Ula'tek", live 2026-08-11) widened the secret surface far beyond
+12.0, and 1.2.0 reported a false clean on the most common aura pattern in retail addons.
+This release adds the 12.1 surface and a `--patch` flag to pin the old one.
+
+### Added
+
+- `--patch=<12.0|12.1>` (default `12.1`), also exposed as the `patch` input of the GitHub
+  Action. `12.0` reproduces the 1.2.0 rule surface byte for byte, for addons still
+  targeting the older client.
+- **WSL012** (error): forbidden operation on a secret aura vector. Taints the returns of
+  `C_UnitAuras.GetUnitAuras`, `GetUnitAuraInstanceIDs`, `GetAuraSlots`, the
+  by-index/slot/instance aura queries and the by-spell lookups; flags `#`,
+  `pairs`/`ipairs` iteration, indexing and table-key use. Boolean-testing the return stays
+  silent, because nil-checking it is the sanctioned pattern, and the shipped guard idiom
+  (`if not aura or issecretvalue(aura.name) then return end`, as in DBM and BigWigs) is
+  credited in full.
+- **WSL013** (error): forbidden operation on a secret unit identity value, covering
+  `UnitClass`, `UnitClassBase`, `UnitRace`, `UnitSex`, `UnitSexBase`, `UnitIsCharmed` and
+  `UnitIsPossessed`, routed through the existing arithmetic, comparison and boolean-test
+  checkers. Literal `"player"` (and `"player"`/`"pet"`/`"vehicle"` for the charm pair, per
+  the 12.1 notes) is exempt.
+- **WSL014** (error): removed or renamed symbols, each message naming the replacement:
+  `SecureAuraHeaderTemplate`, `C_UnitAuras.TriggerPrivateAuraShowDispelType`,
+  `CanAccessObject`, `UIParentLoadAddOn`.
+- **WSL015** (warning): deprecated `getglobal`/`setglobal`.
+- **WSL016** (warning): `showCountdownFrame` passed to a private-aura API. The field was
+  renamed to `showCooldownFrame` and the old name is silently ignored, so the cooldown
+  swipe disappears with no Lua error. Caught inline and through a local args table.
+- **WSL017** (error): forbidden-aspect operations on AuraButtons and AuraContainers:
+  script handler installation, event registration, input calls and focus queries, matched
+  to the UntrustedScriptExecution, EventRegistrations, ScriptedInput and QueryFocus
+  aspects. AuraButtons are recognised from `CreateFrame` and from `initializeFrame`
+  callbacks; construction itself is never flagged.
+
+### Measured
+
+On the same 12-addon corpus as 1.2.0: `--patch=12.0` reproduces 1.2.0 exactly (20 errors,
+90 warnings, 3 of 12 failing). The default 12.1 surface reports 273 errors and 117
+warnings, failing 8 of 12, dominated by WSL012 (148) and WSL013 (104). DBM and BigWigs
+report zero WSL012 because both already guard every aura lookup; the findings sit in the
+addons that have not done that work yet. WSL016 catches the `showCountdownFrame` in oUF's
+`privateauras.lua` and both vendored copies of it (KkthnxUI, SpartanUI).
+
+WSL012 and WSL013 gate builds without `--strict`. Unlike the `SecretReturns` tier, they
+rest on the 12.1 notes stating the behaviour outright ("will now either return full
+secrets or nil when called by addons") rather than on a documentation marker.
+
+### Clone check
+
+The six rules reuse the existing machinery rather than shipping parallel bodies: WSL012
+and WSL013 are taint seeds routed through the existing operator checkers via a one-line
+rule-resolution step, and WSL014/WSL015 share one table-driven removed-call check. The
+new standalone bodies (WSL016 field tracking, WSL017 widget tagging) parallel nothing in
+the codebase; highest pairwise similarity across all new functions is below 40%.
+
+## 1.2.0 - 2026-08-24
+
+- Flavour-aware `.toc` discovery: descends up to three levels, skips folders whose every
+  `.toc` targets Classic, announces blind walks. Fixed WeakAuras-style repos silently
+  bypassing the `.toc` mechanism. Classic contamination in strict findings: 8 of 118 to 0
+  of 110.
+
+## 1.1.0 - 2026-08-24
+
+- Only `WSL008` fails a build by default; everything resting on `SecretReturns` reports
+  as a warning, with `--strict` to raise it. The default is correct under either reading
+  of the documentation.
+
+## 1.0.0 - 2026-08-24
+
+- First release: rules WSL001-WSL011, taint tracking, guard detection, `.toc`/XML
+  resolution, three reporters, GitHub Action, vendored snapshot of Blizzard's generated
+  API documentation.

package/README.md

@@ -1,8 +1,8 @@
 # wow-secret-lint
 
-Static analysis for World of Warcraft **retail** addons. It maps where your Lua touches Blizzard's secret-value API, and hard-fails your build on the one thing that is certain to break.
+Static analysis for World of Warcraft **retail** addons. It maps where your Lua touches Blizzard's secret-value API, and hard-fails your build on the things Blizzard documents as certain to break.
 
-Patch 12.0 introduced [secret values](https://warcraft.wiki.gg/wiki/Secret_Values). A lot of the API now hands your addon a value you are allowed to store, pass around and print, but not to do arithmetic on, compare, index, call, or measure with `#`. When tainted code does one of those, the wiki is blunt about the result:
+Patch 12.0 introduced [secret values](https://warcraft.wiki.gg/wiki/Secret_Values). A lot of the API now hands your addon a value you are allowed to store, pass around and print, but not to do arithmetic on, compare, index, call, or measure with `#`. Patch 12.1 (Curse of Ula'tek, live 2026-08-11) [widened that surface enormously](https://warcraft.wiki.gg/wiki/Patch_12.1.0/API_changes): every `UnitAura` API returns full secrets or nil while auras are secret, seven unit identity APIs joined them, and the new AuraButton/AuraContainer frames carry forbidden aspects. When tainted code does something disallowed, the wiki is blunt about the result:
 
 > When an operation that is not allowed is performed, the result will be an **immediate** Lua error.
 
@@ -17,7 +17,7 @@ That one is [KkthnxUI#121](https://github.com/Kkthnx-Wow/KkthnxUI/issues/121), f
 
 `wow-secret-lint` reads Blizzard's own generated API documentation, tracks which of your locals hold a secret, and tells you where you touch one.
 
-**It reports, it does not accuse.** Exactly one rule fails your build by default: `WSL008`, registering a combat log event, which Blizzard documents as a hard error. Everything else is a warning, because whether those APIs really hand a secret to tainted code on every call is not something static analysis can confirm. Run `--strict` to gate on the rest once you have decided you want that. [The reasoning is spelled out below](#the-open-question-on-severity) and it is worth two minutes before you wire this into CI.
+**It reports, it does not accuse.** The rules that fail your build by default are the ones Blizzard states outright: `WSL008` (combat log registration errors), and the 12.1 rules `WSL012`/`WSL013` (aura and identity APIs "will now either return full secrets or nil when called by addons"), `WSL014` (the symbol no longer exists) and `WSL017` (forbidden aspects). The 12.0-era `SecretReturns` tier stays a warning, because whether those APIs really hand a secret to tainted code on every call is not something static analysis can confirm; run `--strict` to gate on it. [The reasoning is spelled out below](#the-open-question-on-severity) and it is worth two minutes before you wire this into CI.
 
 ## Install
 
@@ -74,6 +74,25 @@ $ npx wow-secret-lint Core/Guarded.lua
 
 Exit code 0.
 
+### The 12.1 aura surface
+
+The most common aura pattern in retail addons stopped working in 12.1. Per the [12.1 API changes](https://warcraft.wiki.gg/wiki/Patch_12.1.0/API_changes): *"APIs like GetUnitAuras and GetUnitAuraInstanceIDs will return a secret vector, meaning addon code will not be able to determine how many auras it contains or iterate through it."* `Core/Auras.lua`:
+
+```lua
+local auras = C_UnitAuras.GetUnitAuras('player'); for i = 1, #auras do print(auras[i].name) end
+```
+
+```
+$ npx wow-secret-lint Core/Auras.lua
+Core/Auras.lua:1:63  error  WSL012  length operator (#) on a secret value: 'auras' derives from C_UnitAuras.GetUnitAuras(), secret in 12.1 while auras are secret (combat, encounters, M+, PvP); show auras with an AuraContainer (AddAuraGroup/AddAuraSlot) instead
+Core/Auras.lua:1:78  error  WSL012  indexed access on a secret value: 'auras' derives from C_UnitAuras.GetUnitAuras(), secret in 12.1 while auras are secret (combat, encounters, M+, PvP); show auras with an AuraContainer (AddAuraGroup/AddAuraSlot) instead
+2 errors, 0 warnings
+```
+
+Exit code 1. Under `--patch=12.0` the same file reports zero findings and exits 0, because the pre-12.1 API really did return an iterable table. `if auras then` stays silent under both, since nil-checking the return is the sanctioned pattern.
+
+None of this comes from Blizzard's generated documentation, which carries no marker for aura secrecy. The 12.1 behaviour is published only in the patch notes, so these rules seed their taint from a list transcribed there, and `--patch` selects whether that list is active.
+
 ### Exit codes
 
 | Code | Meaning |
@@ -107,6 +126,7 @@ Inputs:
 | Input | Default | Description |
 | --- | --- | --- |
 | `path` | `.` | addon folder, `.toc`, or `.lua`. Several allowed, space separated |
+| `patch` | `12.1` | patch surface to check; `12.0` pins the pre-12.1 rule set |
 | `args` | `""` | extra CLI arguments, e.g. `--conditional=warn --disable=WSL011` |
 | `format` | `github` | `github`, `stylish`, or `json` |
 
@@ -114,7 +134,7 @@ Outputs: `errors`, `warnings`.
 
 ## Rules
 
-Every rule maps to one sentence Blizzard publishes. `wow-secret-lint --rules` prints the table with the source for each. Only `WSL008` fails a build by default.
+Every rule maps to one sentence Blizzard publishes. `wow-secret-lint --rules` prints the table with the source for each. WSL008, WSL012, WSL013, WSL014 and WSL017 fail a build by default; the rest are warnings.
 
 | Rule | Severity | What it catches |
 | --- | --- | --- |
@@ -129,11 +149,29 @@ Every rule maps to one sentence Blizzard publishes. `wow-secret-lint --rules` pr
 | WSL009 | warning | secret crosses into a function in this file that never guards it |
 | WSL010 | warning | conditionally secret value used with no guard anywhere in scope |
 | WSL011 | warning | `tostring()` on a secret value |
+| WSL012 | error | 12.1: `#`, iteration, indexing or table-key use of a secret aura vector |
+| WSL013 | error | 12.1: arithmetic, comparison or boolean test on a secret unit identity value |
+| WSL014 | error | 12.1: removed or renamed symbol; each message names the replacement |
+| WSL015 | warning | 12.1: deprecated `getglobal`/`setglobal` |
+| WSL016 | warning | 12.1: `showCountdownFrame` passed to a private-aura API |
+| WSL017 | error | 12.1: forbidden-aspect operation on an AuraButton or AuraContainer |
 
 WSL008 comes from the [12.0.0 API changes](https://warcraft.wiki.gg/wiki/Patch_12.0.0/API_changes): *"COMBAT_LOG_EVENT and COMBAT_LOG_EVENT_UNFILTERED will error when trying to register them."* Use `COMBAT_LOG_EVENT_INTERNAL_UNFILTERED` or the `C_CombatLog` namespace.
 
 WSL011 is a warning on purpose. `tostring` is absent from the wiki's allowed list but is not listed as forbidden either, so it stays a warning until someone confirms it in game.
 
+### The 12.1 rules in detail
+
+**WSL012** taints `C_UnitAuras.GetUnitAuras`, `GetUnitAuraInstanceIDs`, `GetAuraSlots`, the by-index/slot/instance queries (`GetAuraDataByIndex`, `GetAuraDataBySlot`, `GetAuraDataByAuraInstanceID`, `GetBuffDataByIndex`, `GetDebuffDataByIndex`) and the by-spell lookups (`GetAuraDataBySpellName`, `GetUnitAuraBySpellID`, `GetPlayerAuraBySpellID`, `GetCooldownAuraBySpellID`), since the notes say all of the UnitAura APIs return full secrets or nil. The by-index family additionally Lua-errors at the call itself while auras are secret, so any downstream use of its result is broken either way. Boolean tests on aura returns are never flagged: the value is a table or nil, and nil-checking it is how the new contract is meant to be consumed. The guard idiom DBM and BigWigs actually ship, `if not aura or issecretvalue(aura.name) then return end`, is credited in full: indexing one field inside a guard call is the test itself, and a guard naming any field vouches for the whole aura. Auras Blizzard explicitly flags as non-secret still come back readable; static analysis cannot know which spell IDs those are, so an unguarded read of one is still reported.
+
+**WSL013** covers the seven unit APIs the 12.1 notes single out: `UnitClass`, `UnitClassBase`, `UnitRace`, `UnitSex`, `UnitSexBase`, plus `UnitIsCharmed`/`UnitIsPossessed` which follow aura secrecy. The findings come out of the same arithmetic, comparison and boolean-test checkers as WSL001/002/007; only the rule id and severity differ. A literal `"player"` token is exempt (a unit is never secret to itself), and the charm pair is exempt for `"player"`, `"pet"` and `"vehicle"`, which the 12.1 notes state outright. A variable token is not exempt, because it can name an arena opponent. The wider identity set from the notes (`UnitGroupRolesAssigned`, `UnitInRaid`, `UnitIsPVP` and friends) stays in the conditional tier for now: turn on `--conditional=warn` to see it.
+
+**WSL014** flags calls to `UIParentLoadAddOn` (renamed `LoadAddOnWithErrorHandling`), `CanAccessObject` (use `FrameScriptObject:CanBeAccessedInContext`), `C_UnitAuras.TriggerPrivateAuraShowDispelType` (removed; use the `showDispelIcon` anchor option) and any `CreateFrame` template list naming `SecureAuraHeaderTemplate` (removed from Mainline; migrate to an AuraContainer). Referencing `UIParentLoadAddOn` without calling it is not flagged, because `if UIParentLoadAddOn then` is how you feature-detect the old client.
+
+**WSL016** exists because this one fails silently: `showCountdownFrame` was renamed `showCooldownFrame` in the private-aura anchor structures, the old field is ignored, and the cooldown swipe just stops appearing with no error to trace. It is caught both inline and through a local args table. oUF's `privateauras.lua` ships this bug today, as do the copies vendored into KkthnxUI and SpartanUI.
+
+**WSL017** knows a local is an AuraContainer or AuraButton when it comes from `CreateFrame("AuraContainer", ...)`/`CreateFrame("AuraButton", ...)` or arrives as the `initializeFrame` callback parameter of `AddAuraGroup`/`AddAuraSlot`/`AddItemEnchantment`. On those it flags `SetScript`/`HookScript`, event registration, input calls (`EnableMouse`, `RegisterForClicks`, `Click`, ...) and focus queries (`IsMouseOver`, ...), naming the forbidden aspect each one trips. Construction itself is never flagged.
+
 ### What it will never flag
 
 The wiki has an explicit allowed list, and flagging any of it is a false positive that gets a linter uninstalled. Each of these has a passing negative test in `test/`:
@@ -165,7 +203,7 @@ npx wow-secret-lint ./MyAddon --secret-guard=IsLocked --access-guard=CanRead
 
 Blizzard marks a second tier in the generated docs: functions that return a secret only while a specific restriction is active. `C_Spell.GetSpellCooldown` carries `SecretWhenCooldownsRestricted`; `C_LFGList.GetSearchResultInfo` carries `SecretInChatMessagingLockdown`; `UnitGUID`, `UnitName` and `UnitClass` carry `SecretWhenUnitIdentityRestricted`. In practice that means "secret in PvP, in restricted instances, and for non-player or pet units in combat". Your code works fine right up until it does not.
 
-That tier is **off by default**, because measured against 12 real addons it produces about one warning per Lua file, which is a tax rather than a signal. Turn it on for a deeper audit:
+Under the default `--patch=12.1`, the seven identity APIs WSL013 covers are promoted out of this tier and report as errors regardless of the `--conditional` setting. The rest of the tier is **off by default**, because measured against 12 real addons it produces about one warning per Lua file, which is a tax rather than a signal. Turn it on for a deeper audit:
 
 ```bash
 npx wow-secret-lint ./MyAddon --conditional=warn    # report as warnings
@@ -194,23 +232,29 @@ That is [BtWLoadouts#67](https://github.com/Breeni/BtWLoadouts/issues/67), reduc
 
 ## Measured on real addons
 
-Run against 12 real retail addons (BigWigs, LittleWigs, DBM, WeakAuras, Details, SpartanUI, KkthnxUI, oUF, Bartender4, Premade Groups Filter, BtWLoadouts, AdvancedInterfaceOptions), 2,209 Lua files:
+Run against 12 real retail addons (BigWigs, LittleWigs, DBM, WeakAuras, Details, SpartanUI, KkthnxUI, oUF, Bartender4, Premade Groups Filter, BtWLoadouts, AdvancedInterfaceOptions), 1,997 Lua files reachable from a retail `.toc`:
 
 | Mode | Errors | Warnings | Addons that would fail CI |
 | --- | --- | --- | --- |
-| default | 20 | 90 | 3 of 12 |
-| `--strict` | 110 | 0 | 5 of 12 |
+| `--patch=12.1` (default) | 273 | 117 | 8 of 12 |
+| `--patch=12.1 --strict` | 383 | 7 | 8 of 12 |
+| `--patch=12.0` | 20 | 90 | 3 of 12 |
+| `--patch=12.0 --strict` | 110 | 0 | 5 of 12 |
+
+The two `12.0` rows are identical to what v1.2.0 reported, which is the point of the flag. The jump to 273 is the 12.1 aura and identity surface landing: 148 WSL012 and 104 WSL013 findings, concentrated exactly where the [PTR forum thread](https://us.forums.blizzard.com/en/wow/t/minicc-and-similar-addons-might-be-partially-broken-in-121/2310937) predicted breakage: Details' aura scanning (80 WSL012), SpartanUI's aura designer and corner indicators (56), oUF's classpower element and the copy of it inside KkthnxUI (5 each), DBM's class-keyed tables (50 WSL013), BigWigs (20 WSL013). WSL016 catches the silently dead `showCountdownFrame` in oUF `privateauras.lua:133` and both copies of it vendored into KkthnxUI and SpartanUI; WSL014 catches SpartanUI calling the renamed `UIParentLoadAddOn`. No addon in the corpus uses AuraContainers yet, so WSL017 measures 0 there and is exercised by fixtures.
 
-Every one of the 20 default errors is `WSL008`, a combat log event registration that Blizzard documents as failing. Those are worth fixing today and nothing else in the default output can fail your build.
+The number worth noticing is the one that is zero: **DBM and BigWigs report no WSL012 at all**, because both already wrap every aura lookup in an `issecretvalue` guard, and the analysis credits that idiom (see below). The linter separates code that has done the 12.1 work from code that has not.
 
-**All 110 are reachable from a retail `.toc`**, checked by resolving every retail `.toc` in each repo and matching it against the findings. Contamination from Classic-flavour code is 0. It was 8 before flavour-aware discovery landed, all of them WeakAuras, which ships only Classic `.toc` files in its repo and was being scanned by a blind directory walk.
+A sample of the WSL012/WSL013 findings across every affected repo was read against its source by hand; each one performs an operation the 12.1 notes document as disallowed, on a value those notes document as secret, with no guard in scope. The pre-12.1 findings are unchanged from v1.2.0, where all 110 strict findings were read by hand.
 
-All 110 were read against their source line by hand and **none contradicts the documented rule**. That is the strongest claim this project can honestly make, and it is not the same as "these 118 lines error in game". Read the next section before you reach for `--strict`.
+Contamination from Classic-flavour code is 0, checked by resolving every retail `.toc` in each repo and matching it against the findings.
 
-SpartanUI's `libs/oUF_Classic` and `libs/LibClassicDurations` do get flagged and that is correct: its single `.toc` declares `## Interface: 120100, 50504, 38002, 20506, 11509`, so those libraries are listed for retail too. Blizzard's own `BlizzardInterfaceCode` is in the corpus only as a parser stress test, 2,274 files with 0 parse errors, since its code runs untainted and cannot violate these rules.
+SpartanUI's `libs/oUF_Classic` and `libs/LibClassicDurations` do get flagged and that is correct: its single `.toc` declares `## Interface: 120100, 50504, 38002, 20506, 11509`, so those libraries are listed for retail too. Blizzard's own `BlizzardInterfaceCode` is in the corpus only as a parser stress test, 2,128 retail files with 0 parse errors, since its code runs untainted and cannot violate these rules.
 
 ## The open question on severity
 
+This section is about the 12.0-era `SecretReturns` tier (WSL001-WSL007 on `UnitHealth` and friends), which stays a warning by default. It does not apply to WSL012/WSL013: those rest on the 12.1 notes stating the behaviour in plain language, not on a documentation marker whose runtime meaning is unconfirmed.
+
 The Secret Values page says functions marked `SecretReturns = true` "unconditionally return secret values", and that is what the error tier is built on. There is evidence pulling the other way and you should know about it.
 
 Searching the issue trackers of DeadlyBossMods, BigWigs, Details and WeakAuras finds **zero** reports mentioning `UnitHealth` and secret values, while this tool flags dozens of `UnitHealth`-derived findings across them. If `UnitHealth` really did hand a secret to tainted code on every call, `UnitHealth(uId) / UnitHealthMax(uId) * 100` in DBM-Core would throw on every boss pull for millions of users, and the trackers would show it.
@@ -229,6 +273,8 @@ Settling it needs someone to run a flagged line in game and watch what happens,
 ```
 --format=<stylish|json|github>  output format (default: stylish)
 --game=<retail|classic>         classic has no secret values and exits 0 immediately
+--patch=<12.0|12.1>             patch surface the built-in rules check (default: 12.1);
+                                12.0 pins the pre-12.1 rule set
 --strict                        raise SecretReturns findings from warning to error
 --conditional=<off|warn|error>  conditionally secret APIs (default: off)
 --secret-guard=<names>          extra is-secret wrapper functions, comma separated
@@ -252,6 +298,8 @@ npx wow-secret-lint --refresh
 
 A scheduled workflow in this repo does that weekly and opens a pull request when the docs move.
 
+The 12.1 aura and identity secrecy is deliberately **not** part of the snapshot: Blizzard's generated documentation carries no marker for it, only the patch notes describe it, so the WSL012/WSL013 API lists live in `src/rules.mjs` with the source quoted, and `--patch` gates them. There is one snapshot, and `--snapshot`/`--refresh` behave the same under either patch.
+
 ## Limitations and non-goals
 
 - **No auto-fixing.** It tells you where; the fix is yours.
@@ -259,7 +307,8 @@ A scheduled workflow in this repo does that weekly and opens a pull request when
 - **No Classic support.** Classic has no secret values, so `--game=classic` exits 0 immediately.
 - **No cross-file interprocedural analysis in v1.** Taint follows plain assignment, table field stores, the return value of a file-local function, and one level of intra-file call-argument passing. A secret that leaves through a global and comes back in another file is not tracked.
 - **No LuaJIT or Lua 5.4 syntax.** Files are parsed as Lua 5.1. WoW accepts a semicolon after `break`, which stock 5.1 does not, so a file that fails on 5.1 gets one retry under the 5.2 grammar before it is reported as a parse error.
-- **Method calls are not resolved to a widget type**, so WSL006 only applies to plain and namespaced calls (`UnitHealth(...)`, `C_CVar.SetCVar(...)`), never to `frame:SetText(...)`.
+- **Method calls are not resolved to a widget type**, so WSL006 only applies to plain and namespaced calls (`UnitHealth(...)`, `C_CVar.SetCVar(...)`), never to `frame:SetText(...)`. WSL017 is the one exception, and its typing is deliberately narrow: a local counts as an AuraContainer/AuraButton only when it comes straight from `CreateFrame` with a literal type string or from an `initializeFrame` callback. A button stored in a table field or passed across files is not tracked.
+- **XML is followed for `<Script>`/`<Include>`, not linted.** A `SecureAuraHeaderTemplate` referenced from an XML `inherits` attribute is invisible to WSL014; only Lua-side `CreateFrame` template strings are checked.
 - **`string.format` output is not tracked as secret.** The wiki names it as the sanctioned way to render a secret, and following it would flood every `SetText` call site. The trade is a known blind spot on `#string.format(...)`.
 - A `.toc` listing a file that is not on disk warns and keeps going. A file that will not parse is reported and the run exits 2.
 
@@ -269,7 +318,7 @@ A scheduled workflow in this repo does that weekly and opens a pull request when
 npm test
 ```
 
-123 tests. The suite covers every rule, the guard forms, the permitted-operations negative cases, the three reporters, the CLI surface, and eight regression fixtures reconstructed from real shipped traces:
+173 tests. The suite covers every rule, the guard forms, the permitted-operations negative cases, the three reporters, the CLI surface, one violating and one clean fixture per 12.1 rule (`test/fixtures/rules-121/`), a fixture proving `--patch=12.0` reproduces the v1.2.0 output byte for byte (`test/fixtures/patch/`), and eight regression fixtures reconstructed from real shipped traces:
 
 | Fixture | Issue |
 | --- | --- |

package/action/index.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { lintPaths, VERSION } from '../src/index.mjs';
 import { format, FORMATS, counts } from '../src/report.mjs';
-import { RULE_IDS } from '../src/rules.mjs';
+import { RULE_IDS, PATCHES, DEFAULT_PATCH } from '../src/rules.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -49,7 +49,15 @@ const fmt = input('format', 'github');
 
 if (!FORMATS.includes(fmt)) fail(`unknown format "${fmt}" (expected one of: ${FORMATS.join(', ')})`);
 
-const options = { conditional: 'off', strict: false, disable: [], secretGuards: [], accessGuards: [], game: 'retail' };
+const options = {
+  conditional: 'off',
+  strict: false,
+  disable: [],
+  secretGuards: [],
+  accessGuards: [],
+  game: 'retail',
+  patch: input('patch', DEFAULT_PATCH),
+};
 let maxWarnings = Infinity;
 
 for (let i = 0; i < extra.length; i++) {
@@ -68,6 +76,9 @@ for (let i = 0; i < extra.length; i++) {
     case '--game':
       options.game = val();
       break;
+    case '--patch':
+      options.patch = val();
+      break;
     case '--disable':
       options.disable.push(...val().split(',').map((s) => s.trim()).filter(Boolean));
       break;
@@ -94,6 +105,9 @@ if (!['off', 'warn', 'error'].includes(options.conditional)) {
 if (!['retail', 'classic'].includes(options.game)) {
   fail(`unknown --game "${options.game}" (expected retail or classic)`);
 }
+if (!PATCHES.includes(options.patch)) {
+  fail(`unknown patch "${options.patch}" (expected ${PATCHES.join(' or ')})`);
+}
 for (const id of options.disable) {
   if (!RULE_IDS.includes(id)) fail(`unknown rule id "${id}" in --disable`);
 }

package/action.yml

@@ -10,6 +10,10 @@ inputs:
     description: 'Addon folder, .toc, or .lua file to lint. Accepts several, space separated.'
     required: false
     default: '.'
+  patch:
+    description: 'Patch surface to check: 12.1 (default) or 12.0 for addons pinned to the older client.'
+    required: false
+    default: '12.1'
   args:
     description: 'Extra CLI arguments, e.g. "--conditional=warn --disable=WSL011".'
     required: false

package/bin/wow-secret-lint.mjs

@@ -7,7 +7,7 @@ import process from 'node:process';
 import { lintPaths, VERSION } from '../src/index.mjs';
 import { format, FORMATS, counts } from '../src/report.mjs';
 import { refreshSnapshot, writeSnapshot, SNAPSHOT_PATH } from '../src/apidata.mjs';
-import { RULES, RULE_IDS } from '../src/rules.mjs';
+import { RULES, RULE_IDS, PATCHES, DEFAULT_PATCH } from '../src/rules.mjs';
 
 const USAGE = `wow-secret-lint ${VERSION}
 Static analysis for World of Warcraft retail addons: finds Secret Value violations
@@ -21,6 +21,9 @@ Usage:
 Options:
   --format=<stylish|json|github>  output format (default: stylish)
   --game=<retail|classic>         classic has no secret values and exits 0 immediately
+  --patch=<12.0|12.1>             which patch surface the built-in rules check
+                                  (default: 12.1). 12.0 pins the pre-12.1 rule set for
+                                  addons still targeting the older client
   --strict                        raise SecretReturns findings from warning to error.
                                   Off by default: see "the open question on severity"
                                   in the README before you gate CI on them.
@@ -52,6 +55,7 @@ function parseArgs(argv) {
   const opts = {
     format: 'stylish',
     game: 'retail',
+    patch: DEFAULT_PATCH,
     conditional: 'off',
     strict: false,
     disable: [],
@@ -78,6 +82,7 @@ function parseArgs(argv) {
     else if (arg === '--strict') opts.strict = true;
     else if (arg.startsWith('--format')) opts.format = value(arg, argv, () => i++);
     else if (arg.startsWith('--game')) opts.game = value(arg, argv, () => i++);
+    else if (arg.startsWith('--patch')) opts.patch = value(arg, argv, () => i++);
     else if (arg.startsWith('--conditional')) opts.conditional = value(arg, argv, () => i++);
     else if (arg.startsWith('--secret-guard')) opts.secretGuards.push(...value(arg, argv, () => i++).split(',').map((s) => s.trim()).filter(Boolean));
     else if (arg.startsWith('--access-guard')) opts.accessGuards.push(...value(arg, argv, () => i++).split(',').map((s) => s.trim()).filter(Boolean));
@@ -152,6 +157,7 @@ async function main() {
 
   if (!FORMATS.includes(opts.format)) fail(`unknown format "${opts.format}" (expected one of: ${FORMATS.join(', ')})`);
   if (!['retail', 'classic'].includes(opts.game)) fail(`unknown game "${opts.game}" (expected retail or classic)`);
+  if (!PATCHES.includes(opts.patch)) fail(`unknown --patch "${opts.patch}" (expected ${PATCHES.join(' or ')})`);
   if (!['warn', 'error', 'off'].includes(opts.conditional)) {
     fail(`unknown --conditional "${opts.conditional}" (expected warn, error or off)`);
   }
@@ -175,6 +181,7 @@ async function main() {
   try {
     merged = await lintPaths(opts.paths, {
       game: opts.game,
+      patch: opts.patch,
       conditional: opts.conditional,
       strict: opts.strict,
       disable: opts.disable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wow-secret-lint",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Maps where a WoW retail addon touches Blizzard's secret-value API, and gates CI on the one error that is certain.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "data/api-snapshot.json",
     "action.yml",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {

package/src/analyze.mjs

@@ -19,6 +19,21 @@ import {
   COMBAT_LOG_EVENTS,
   COMBAT_LOG_REPLACEMENT,
   booleanTestSeverity,
+  DEFAULT_PATCH,
+  AURA_SECRET_APIS,
+  IDENTITY_SECRET_APIS,
+  SELF_EXEMPT_TOKENS,
+  AURA_STATE_IDENTITY_APIS,
+  CATEGORY_RULES,
+  ITERATORS,
+  AURA_SUGGESTION,
+  REMOVED_CALLS,
+  REMOVED_TEMPLATE,
+  REMOVED_TEMPLATE_MESSAGE,
+  RENAMED_STRUCT_FIELDS,
+  ASPECT_FRAME_TYPES,
+  AURA_GROUP_METHODS,
+  FORBIDDEN_ASPECT_METHODS,
 } from './rules.mjs';
 
 const ARITHMETIC = new Set(['+', '-', '*', '/', '%', '^']);
@@ -86,6 +101,10 @@ class Analyzer {
     this.bindingSeq = 0;
     this.callDepth = 0;
     this.analysedWithTaint = new Set();
+    this.patch121 = options.patch !== '12.0';
+    this.widgetOf = new Map(); // dotted path -> 'AuraContainer' | 'AuraButton'
+    this.tableFields = new Map(); // dotted path -> Map(fieldName -> key node)
+    this.guardArgDepth = 0; // > 0 while evaluating the arguments of a guard or scrubber call
   }
 
   // ---------------------------------------------------------------- findings
@@ -100,8 +119,13 @@ class Analyzer {
     // Findings that rest on SecretReturns report as warnings unless --strict. Whether those
     // APIs really hand a secret to tainted code on every call is unconfirmed in game, so the
     // default is an inventory of exposure, not a verdict. Rules with no taint behind them
-    // (WSL008) are deterministic and keep their severity.
-    if (taint && taint.kind === 'secret' && sev === 'error' && !this.options.strict) sev = 'warning';
+    // (WSL008, WSL014-017) are deterministic and keep their severity, as do the 12.1 aura
+    // and identity rules: the patch notes state the secrecy outright and every player enters
+    // the states that activate it.
+    const patchBreaking = ruleId === 'WSL012' || ruleId === 'WSL013';
+    if (taint && taint.kind === 'secret' && sev === 'error' && !this.options.strict && !patchBreaking) {
+      sev = 'warning';
+    }
     if (this.options.disable.has(ruleId)) return;
     const p = pos(node);
     const key = `${ruleId}:${p.line}:${p.column}`;
@@ -123,6 +147,12 @@ class Analyzer {
   describe(taint) {
     if (!taint) return 'a secret value';
     const name = taint.label ? `'${taint.label}' ` : '';
+    if (taint.category === 'aura') {
+      return `${name}derives from ${taint.origin}(), secret in 12.1 while auras are secret (combat, encounters, M+, PvP); ${AURA_SUGGESTION}`;
+    }
+    if (taint.category === 'identity') {
+      return `${name}derives from ${taint.origin}(), whose returns are secret in 12.1 while the unit's identity is secret`;
+    }
     if (taint.kind === 'conditional') {
       const why = taint.conditions && taint.conditions.length ? taint.conditions.join(', ') : 'a runtime restriction';
       return `${name}derives from ${taint.origin}() (conditionally secret: ${why})`;
@@ -156,7 +186,7 @@ class Analyzer {
 
   // ------------------------------------------------------------------ taint
 
-  makeTaint({ kind, origin, type, conditions, structure, label, bindingId, container }) {
+  makeTaint({ kind, origin, type, conditions, structure, label, bindingId, container, category }) {
     return {
       kind,
       origin,
@@ -165,11 +195,18 @@ class Analyzer {
       structure: structure ?? null,
       // A documented structure is not itself a secret; its unmarked fields are.
       container: container === true,
+      // 'aura' or 'identity' reroutes operator findings to WSL012/WSL013.
+      category: category ?? null,
       label: label ?? null,
       bindingId: bindingId ?? null,
     };
   }
 
+  /** Operator findings on a categorised taint report as the 12.1 rule for that category. */
+  ruleFor(defaultId, taint) {
+    return taint && taint.category ? CATEGORY_RULES[taint.category] : defaultId;
+  }
+
   /** Resolve the callee of a CallExpression to a documented API name, or null. */
   calleeName(node) {
     const base = node.base;
@@ -191,6 +228,18 @@ class Analyzer {
   /** Taint carried by return position `index` (0-based) of a documented API call. */
   returnTaint(name, entry, index, node) {
     const ret = entry.returns && entry.returns[index] ? entry.returns[index] : null;
+    // Aura secrecy is behavioural, so the generated docs carry no marker for it and the
+    // 12.1 lists seed it here, ahead of the snapshot's own annotations. All return
+    // positions are secret, and no structure is recorded because the value is a full
+    // secret: reading a field of it is itself the violation.
+    if (this.patch121) {
+      if (AURA_SECRET_APIS.has(name)) {
+        return this.makeTaint({ kind: 'secret', origin: name, type: ret ? ret.type : null, category: 'aura' });
+      }
+      if (IDENTITY_SECRET_APIS.has(name) && !selfExempt(name, node)) {
+        return this.makeTaint({ kind: 'secret', origin: name, type: ret ? ret.type : null, category: 'identity' });
+      }
+    }
     if (ret && ret.neverSecret) return null;
     const type = ret ? ret.type : null;
     const structure = type && this.api.structures[type] ? type : null;
@@ -338,6 +387,14 @@ class Analyzer {
         if (recv) paths.push(recv);
       }
       if (!paths.length) return empty;
+      // An aura is secret or readable as a unit, so a guard naming one field of a
+      // category-tainted value (issecretvalue(aura.name)) vouches for the whole value.
+      for (const p of [...paths]) {
+        const root = p.split('.')[0];
+        if (root === p) continue;
+        const t = scope.get(root);
+        if (t && t.category) paths.push(root);
+      }
       const marks = paths.map((p) => ({ path: p, prefix: g.prefix }));
       return g.safeWhen ? { whenTrue: marks, whenFalse: [] } : { whenTrue: [], whenFalse: marks };
     }
@@ -544,14 +601,14 @@ class Analyzer {
         if (t.type === 'MemberExpression' || t.type === 'IndexExpression') {
           const baseTaint = this.taintOf(t.base, scope);
           if (baseTaint && !baseTaint.container && !baseTaint.structure) {
-            this.report('WSL005', t, `indexed assignment on a secret value: ${this.describe(baseTaint)}`, {
+            this.report(this.ruleFor('WSL005', baseTaint), t, `indexed assignment on a secret value: ${this.describe(baseTaint)}`, {
               taint: baseTaint,
             });
           }
           if (t.type === 'IndexExpression') {
             const keyTaint = this.taintOf(t.index, scope);
             if (keyTaint) {
-              this.report('WSL005', t.index, `secret value used as a table key: ${this.describe(keyTaint)}`, {
+              this.report(this.ruleFor('WSL005', keyTaint), t.index, `secret value used as a table key: ${this.describe(keyTaint)}`, {
                 taint: keyTaint,
               });
             }
@@ -595,6 +652,7 @@ class Analyzer {
           this.cleared.delete(path);
         }
       }
+      if (this.patch121) this.trackPatchState(target, i < inits.length ? inits[i] : null);
     });
     return null;
   }
@@ -621,10 +679,10 @@ class Analyzer {
         const t = lt ?? rt;
         if (!t) return;
         if (ARITHMETIC.has(node.operator)) {
-          this.report('WSL001', lt ? node.left : node.right, `arithmetic on a secret value: ${this.describe(t)}`, { taint: t });
+          this.report(this.ruleFor('WSL001', t), lt ? node.left : node.right, `arithmetic on a secret value: ${this.describe(t)}`, { taint: t });
           if (lt && rt) this.markReported(rt);
         } else if (RELATIONAL.has(node.operator)) {
-          this.report('WSL002', lt ? node.left : node.right, `comparison of a secret value: ${this.describe(t)}`, { taint: t });
+          this.report(this.ruleFor('WSL002', t), lt ? node.left : node.right, `comparison of a secret value: ${this.describe(t)}`, { taint: t });
           if (lt && rt) this.markReported(rt);
         } else if (node.operator === '..') {
           // Explicitly allowed by the wiki for string and number secrets.
@@ -648,9 +706,9 @@ class Analyzer {
         const t = this.taintOf(node.argument, scope);
         if (!t) return;
         if (node.operator === '#') {
-          this.report('WSL004', node.argument, `length operator (#) on a secret value: ${this.describe(t)}`, { taint: t });
+          this.report(this.ruleFor('WSL004', t), node.argument, `length operator (#) on a secret value: ${this.describe(t)}`, { taint: t });
         } else if (node.operator === '-') {
-          this.report('WSL001', node.argument, `arithmetic on a secret value: ${this.describe(t)}`, { taint: t });
+          this.report(this.ruleFor('WSL001', t), node.argument, `arithmetic on a secret value: ${this.describe(t)}`, { taint: t });
         } else if (node.operator === 'not') {
           this.booleanTest(node.argument, t);
         }
@@ -662,14 +720,18 @@ class Analyzer {
         if (node.type === 'IndexExpression') this.evaluate(node.index, scope);
         const baseTaint = this.taintOf(node.base, scope);
         if (baseTaint && !baseTaint.container && !baseTaint.structure) {
-          this.report('WSL005', node, `indexed access on a secret value: ${this.describe(baseTaint)}`, {
-            taint: baseTaint,
-          });
+          if (baseTaint.category && this.guardArgDepth > 0) {
+            this.markUse(baseTaint, true);
+          } else {
+            this.report(this.ruleFor('WSL005', baseTaint), node, `indexed access on a secret value: ${this.describe(baseTaint)}`, {
+              taint: baseTaint,
+            });
+          }
         }
         if (node.type === 'IndexExpression') {
           const keyTaint = this.taintOf(node.index, scope);
           if (keyTaint) {
-            this.report('WSL005', node.index, `secret value used as a table key: ${this.describe(keyTaint)}`, {
+            this.report(this.ruleFor('WSL005', keyTaint), node.index, `secret value used as a table key: ${this.describe(keyTaint)}`, {
               taint: keyTaint,
             });
           }
@@ -719,7 +781,7 @@ class Analyzer {
       const target = baseIsMethod ? node.base.base : node.base;
       const t = baseIsMethod ? null : this.taintOf(target, scope);
       if (t && !t.container) {
-        this.report('WSL003', node.base, `call of a secret value as-if it were a function: ${this.describe(t)}`, {
+        this.report(this.ruleFor('WSL003', t), node.base, `call of a secret value as-if it were a function: ${this.describe(t)}`, {
           taint: t,
         });
       }
@@ -727,7 +789,17 @@ class Analyzer {
       else if (node.base.type !== 'Identifier') this.evaluate(node.base, scope);
     }
 
+    // AddAuraGroup and friends hand an AuraButton to their initializeFrame callback, so tag
+    // that parameter before the callback body is analysed, and untag it afterwards.
+    const buttonParams = this.patch121 ? this.tagInitializeFrameParams(callee, args) : [];
+    // `issecretvalue(aura.name)` indexes the aura in order to test it; that read is the
+    // guard idiom DBM and BigWigs ship, not a violation.
+    const guardCall =
+      callee && (this.guardShape(callee) || (!callee.method && SCRUBBERS.has(callee.name)));
+    if (guardCall) this.guardArgDepth += 1;
     for (const a of args) this.evaluate(a, scope);
+    if (guardCall) this.guardArgDepth -= 1;
+    for (const p of buttonParams) this.widgetOf.delete(p);
 
     if (!callee) return;
     const name = callee.name;
@@ -742,8 +814,36 @@ class Analyzer {
       }
     }
 
+    if (this.patch121) {
+      if (!callee.method) {
+        const removed = REMOVED_CALLS[name];
+        if (removed) this.report(removed.ruleId, node, removed.message);
+        if (name === 'CreateFrame') this.checkCreateFrameTemplates(args);
+      } else {
+        const recv = node.base && node.base.base ? this.pathOf(node.base.base) : null;
+        const widgetType = recv ? this.widgetOf.get(recv) : null;
+        const forbidden = widgetType ? FORBIDDEN_ASPECT_METHODS[widgetType][name] : null;
+        if (forbidden) {
+          this.report(
+            'WSL017',
+            node,
+            `${forbidden.verb} on an ${widgetType} is disallowed by its ${forbidden.aspect} forbidden aspect: ${recv}:${name}()`
+          );
+        }
+      }
+    }
+
     const argTaints = args.map((a) => this.taintOf(a, scope));
 
+    if (this.patch121 && !callee.method && ITERATORS.has(name)) {
+      for (let i = 0; i < args.length; i++) {
+        const t = argTaints[i];
+        if (t && t.category) {
+          this.report(CATEGORY_RULES[t.category], args[i], `iteration with ${name}() over a secret value: ${this.describe(t)}`, { taint: t });
+        }
+      }
+    }
+
     if (!callee.method && SCRUBBERS.has(name)) {
       for (const t of argTaints) this.markUse(t, true);
       return;
@@ -762,6 +862,7 @@ class Analyzer {
 
     const entry = callee.method ? null : this.apiEntry(name);
     if (entry) {
+      if (this.patch121) this.checkRenamedStructFields(entry, args);
       const sa = entry.secretArguments;
       for (let i = 0; i < args.length; i++) {
         const t = argTaints[i];
@@ -788,6 +889,93 @@ class Analyzer {
     for (const t of argTaints) this.markUse(t, false);
   }
 
+  // ------------------------------------------------------------- patch 12.1 checks
+
+  /** Tag initializeFrame callback parameters as AuraButtons; returns the names to untag. */
+  tagInitializeFrameParams(callee, args) {
+    if (!callee || !callee.method || !AURA_GROUP_METHODS.has(callee.name)) return [];
+    const tagged = [];
+    for (const a of args) {
+      if (!a || a.type !== 'TableConstructorExpression') continue;
+      for (const f of a.fields) {
+        if (f.type !== 'TableKeyString' || f.key.name !== 'initializeFrame') continue;
+        if (!f.value || f.value.type !== 'FunctionDeclaration') continue;
+        const p = f.value.parameters && f.value.parameters[0];
+        if (p && p.type === 'Identifier' && !this.widgetOf.has(p.name)) {
+          this.widgetOf.set(p.name, 'AuraButton');
+          tagged.push(p.name);
+        }
+      }
+    }
+    return tagged;
+  }
+
+  /** WSL014: a CreateFrame template list naming the removed SecureAuraHeaderTemplate. */
+  checkCreateFrameTemplates(args) {
+    for (const a of args) {
+      const s = stringValue(a);
+      if (!s || !s.includes(REMOVED_TEMPLATE)) continue;
+      if (s.split(',').some((part) => part.trim() === REMOVED_TEMPLATE)) {
+        this.report('WSL014', a, REMOVED_TEMPLATE_MESSAGE);
+      }
+    }
+  }
+
+  /**
+   * WSL016: a field 12.1 renamed, passed inside a documented options structure. The old
+   * name is ignored at runtime with no Lua error, which is why it needs a static check.
+   */
+  checkRenamedStructFields(entry, args) {
+    const docArgs = entry.args || [];
+    for (let i = 0; i < args.length && i < docArgs.length; i++) {
+      const struct = docArgs[i] && docArgs[i].type ? this.api.structures[docArgs[i].type] : null;
+      if (!struct || !struct.fields) continue;
+      const passed =
+        args[i].type === 'TableConstructorExpression'
+          ? constructorFields(args[i])
+          : args[i].type === 'Identifier'
+            ? this.tableFields.get(args[i].name)
+            : null;
+      if (!passed) continue;
+      for (const [oldField, newField] of Object.entries(RENAMED_STRUCT_FIELDS)) {
+        if (!Object.prototype.hasOwnProperty.call(struct.fields, newField)) continue;
+        const keyNode = passed.get(oldField);
+        if (keyNode) {
+          this.report(
+            'WSL016',
+            keyNode,
+            `${oldField} was removed from ${docArgs[i].type} in 12.1 and is silently ignored (the cooldown swipe never shows); use ${newField} instead`
+          );
+        }
+      }
+    }
+  }
+
+  /** Keep the path -> widget-type and path -> table-fields maps in step with assignments. */
+  trackPatchState(target, init) {
+    const path = target.type === 'Identifier' ? target.name : this.pathOf(target);
+    if (!path) return;
+    // `args.showCountdownFrame = true` after the constructor still counts as a field.
+    if (target.type === 'MemberExpression') {
+      const fields = this.tableFields.get(this.pathOf(target.base));
+      if (fields) fields.set(target.identifier.name, target);
+    }
+    this.widgetOf.delete(path);
+    this.tableFields.delete(path);
+    if (!init) return;
+    if (init.type === 'TableConstructorExpression') {
+      this.tableFields.set(path, constructorFields(init));
+      return;
+    }
+    if (init.type === 'CallExpression') {
+      const callee = this.calleeName(init);
+      if (callee && !callee.method && callee.name === 'CreateFrame') {
+        const frameType = stringValue(init.arguments[0]);
+        if (frameType && ASPECT_FRAME_TYPES.has(frameType)) this.widgetOf.set(path, frameType);
+      }
+    }
+  }
+
   crossBoundary(local, name, args, argTaints, node, scope) {
     const tainted = argTaints.map((t, i) => (t ? i : -1)).filter((i) => i >= 0);
     if (!tainted.length) return;
@@ -898,6 +1086,14 @@ class Analyzer {
 
   booleanTest(node, taint) {
     if (taint.container) return;
+    // The 12.1 aura APIs return a table or nil, never a boolean, and nil-checking the
+    // return is the sanctioned pattern, so a boolean test on aura taint stays silent.
+    // (The AuraData structure left the generated docs in 12.1, so the type lookup below
+    // cannot vouch for it any more.)
+    if (taint.category === 'aura') {
+      this.markUse(taint, true);
+      return;
+    }
     const sev = booleanTestSeverity(taint.type, this.api.structures);
     if (!sev) {
       this.markUse(taint, true);
@@ -907,7 +1103,7 @@ class Analyzer {
       sev === 'error'
         ? `its documented return type is bool`
         : `its documented return type is unknown, so this may be a boolean secret`;
-    this.report('WSL007', node, `boolean test on a secret value (${why}): ${this.describe(taint)}`, {
+    this.report(this.ruleFor('WSL007', taint), node, `boolean test on a secret value (${why}): ${this.describe(taint)}`, {
       severity: sev,
       taint,
     });
@@ -970,6 +1166,27 @@ function exits(body) {
   return !!last && (last.type === 'ReturnStatement' || last.type === 'BreakStatement');
 }
 
+/** True when a literal unit token keeps this identity API non-secret (see rules.mjs). */
+function selfExempt(name, node) {
+  const token = node && Array.isArray(node.arguments) ? stringValue(node.arguments[0]) : null;
+  if (token === null) return false;
+  if (AURA_STATE_IDENTITY_APIS.has(name)) return SELF_EXEMPT_TOKENS.has(token);
+  return token === 'player';
+}
+
+/** String-keyed fields of a table constructor, mapped to their key nodes. */
+function constructorFields(tableNode) {
+  const fields = new Map();
+  for (const f of tableNode.fields) {
+    if (f.type === 'TableKeyString') fields.set(f.key.name, f.key);
+    else if (f.type === 'TableKey') {
+      const k = stringValue(f.key);
+      if (k !== null) fields.set(k, f.key);
+    }
+  }
+  return fields;
+}
+
 /**
  * Analyse one Lua source file.
  * @returns {{ findings: object[], parseError: object|null }}
@@ -981,6 +1198,7 @@ export function analyzeSource(source, filePath, api, options = {}) {
     secretGuards: new Set(options.secretGuards ?? []),
     accessGuards: new Set(options.accessGuards ?? []),
     strict: options.strict === true,
+    patch: options.patch ?? DEFAULT_PATCH,
   };
   const parseOptions = { locations: true, ranges: false, comments: false, scope: false };
   let ast;

package/src/index.mjs

@@ -5,14 +5,15 @@ import { relative, resolve, dirname } from 'node:path';
 import { analyzeSource } from './analyze.mjs';
 import { loadSnapshot } from './apidata.mjs';
 import { findTocFilesDeep, parseToc, resolveTocFiles, collectLuaFiles, isRetailToc, toPosix } from './toc.mjs';
+import { DEFAULT_PATCH } from './rules.mjs';
 
-export { RULES, RULE_IDS } from './rules.mjs';
+export { RULES, RULE_IDS, PATCHES, DEFAULT_PATCH } from './rules.mjs';
 export { analyzeSource } from './analyze.mjs';
 export { loadSnapshot, refreshSnapshot, writeSnapshot, extractFile, buildIndex, SNAPSHOT_PATH } from './apidata.mjs';
 export { format, formatStylish, formatJson, formatGithub, FORMATS } from './report.mjs';
 export { parseToc, findTocFiles, findTocFilesDeep, isRetailToc } from './toc.mjs';
 
-export const VERSION = '1.2.0';
+export const VERSION = '1.3.0';
 
 /**
  * Lint an addon directory or a single .lua/.toc file.
@@ -20,6 +21,7 @@ export const VERSION = '1.2.0';
  * @param {string} target       path to an addon folder, a .toc, or a .lua file
  * @param {object} options
  * @param {'retail'|'classic'} options.game
+ * @param {'12.0'|'12.1'} options.patch  which patch surface the built-in rules check (default 12.1)
  * @param {'warn'|'error'|'off'} options.conditional  how to treat conditionally secret APIs
  * @param {string[]} options.disable  rule ids to silence
  * @param {string[]} options.secretGuards  extra is-secret wrapper names, e.g. IsSecret
@@ -35,6 +37,7 @@ export async function lint(target, options = {}) {
     version: VERSION,
     target,
     game,
+    patch: options.patch ?? DEFAULT_PATCH,
     filesScanned: 0,
     findings: [],
     parseErrors: [],
@@ -121,6 +124,7 @@ export async function lint(target, options = {}) {
     secretGuards: new Set(options.secretGuards ?? []),
     accessGuards: new Set(options.accessGuards ?? []),
     strict: options.strict === true,
+    patch: options.patch,
   };
 
   for (const file of files) {
@@ -152,6 +156,7 @@ export function byLocation(a, b) {
 export async function lintPaths(paths, options = {}) {
   const merged = {
     version: VERSION,
+    patch: options.patch ?? DEFAULT_PATCH,
     filesScanned: 0,
     findings: [],
     parseErrors: [],

package/src/report.mjs

@@ -54,6 +54,7 @@ export function formatJson(result) {
   return JSON.stringify(
     {
       version: result.version,
+      patch: result.patch,
       snapshot: {
         source: result.snapshot.source,
         generated: result.snapshot.generated,

package/src/rules.mjs

@@ -3,6 +3,10 @@
 
 const WIKI = 'https://warcraft.wiki.gg/wiki/Secret_Values';
 const PATCH = 'https://warcraft.wiki.gg/wiki/Patch_12.0.0/API_changes';
+const PATCH121 = 'https://warcraft.wiki.gg/wiki/Patch_12.1.0/API_changes';
+
+export const PATCHES = ['12.0', '12.1'];
+export const DEFAULT_PATCH = '12.1';
 
 export const RULES = {
   WSL001: {
@@ -60,6 +64,42 @@ export const RULES = {
     summary: 'tostring() on a secret value',
     source: `Inferred. tostring is absent from the allowed list on ${WIKI} and is not documented as forbidden either; kept a warning until confirmed in game.`,
   },
+  WSL012: {
+    severity: 'error',
+    patch: '12.1',
+    summary: 'forbidden operation on a secret aura vector',
+    source: `${PATCH121} : "when auras are secret (during combat, encounters, M+, and PvP matches), all of the UnitAura APIs will now either return full secrets or nil when called by addons. That means that APIs like GetUnitAuras and GetUnitAuraInstanceIDs will return a secret vector, meaning addon code will not be able to determine how many auras it contains or iterate through it for display."`,
+  },
+  WSL013: {
+    severity: 'error',
+    patch: '12.1',
+    summary: 'forbidden operation on a secret unit identity value',
+    source: `${PATCH121} : "A number of Unit APIs have been changed to return secret values when the unit's identity is secret", naming UnitClass, UnitClassBase, UnitRace, UnitSex and UnitSexBase; "UnitIsCharmed and UnitIsPossessed APIs now return secret values when auras are secret."`,
+  },
+  WSL014: {
+    severity: 'error',
+    patch: '12.1',
+    summary: 'symbol removed or renamed in 12.1',
+    source: `${PATCH121} : "UIParentLoadAddOn has been renamed to LoadAddOnWithErrorHandling." / "CanAccessObject has been replaced with FrameScriptObject:CanBeAccessedInContext." / "SecureAuraHeaderTemplate has been removed from Mainline"; C_UnitAuras.TriggerPrivateAuraShowDispelType is in the Removed list.`,
+  },
+  WSL015: {
+    severity: 'warning',
+    patch: '12.1',
+    summary: 'deprecated getglobal/setglobal',
+    source: `${PATCH121} : "Deprecated getglobal and setglobal."`,
+  },
+  WSL016: {
+    severity: 'warning',
+    patch: '12.1',
+    summary: 'showCountdownFrame passed to a private-aura API',
+    source: `${PATCH121} : showCountdownFrame was removed from AddPrivateAuraAnchorArgs and UnitPrivateAuraAnchorInfo, replaced by showCooldownFrame, showCooldownEdge and showDispelIcon. The field is silently ignored, so the cooldown swipe stops appearing with no Lua error.`,
+  },
+  WSL017: {
+    severity: 'error',
+    patch: '12.1',
+    summary: 'forbidden-aspect operation on an AuraButton or AuraContainer',
+    source: `${PATCH121} : "Aura Buttons have had the following Forbidden Aspects applied to them: UntrustedScriptExecution, UntrustedLayoutScriptExecution, AlwaysPropagateInput, ScriptedInput, and QueryFocus" / "Aura Containers have had the EventRegistrations Forbidden Aspect applied to them."`,
+  },
 };
 
 export const RULE_IDS = Object.keys(RULES);
@@ -137,6 +177,143 @@ const NON_BOOL_TYPES = new Set([
   'textureKit',
 ]);
 
+// ------------------------------------------------------------- patch 12.1 surface
+//
+// None of this is in Blizzard's generated documentation. Aura secrecy is behavioural
+// ("when auras are secret ... return full secrets or nil"), documented only in the 12.1
+// patch notes, so the snapshot cannot carry it and these lists seed the taint instead.
+
+/**
+ * APIs whose returns are a secret aura vector or secret aura data in 12.1. Taints they
+ * produce carry category 'aura' and report as WSL012. Bare names are listed too because
+ * the snapshot registers global aliases for namespaced functions.
+ */
+export const AURA_SECRET_APIS = new Set(
+  [
+    'C_UnitAuras.GetUnitAuras',
+    'C_UnitAuras.GetUnitAuraInstanceIDs',
+    'C_UnitAuras.GetAuraSlots',
+    'C_UnitAuras.GetAuraDataByIndex',
+    'C_UnitAuras.GetAuraDataBySlot',
+    'C_UnitAuras.GetAuraDataByAuraInstanceID',
+    'C_UnitAuras.GetBuffDataByIndex',
+    'C_UnitAuras.GetDebuffDataByIndex',
+    // "all of the UnitAura APIs" per the 12.1 notes, so the by-spell lookups too.
+    'C_UnitAuras.GetAuraDataBySpellName',
+    'C_UnitAuras.GetUnitAuraBySpellID',
+    'C_UnitAuras.GetPlayerAuraBySpellID',
+    'C_UnitAuras.GetCooldownAuraBySpellID',
+  ].flatMap((n) => [n, n.slice(n.indexOf('.') + 1)])
+);
+
+/** Unit APIs the 12.1 notes name as returning secrets. Category 'identity', rule WSL013. */
+export const IDENTITY_SECRET_APIS = new Set([
+  'UnitClass',
+  'UnitClassBase',
+  'UnitRace',
+  'UnitSex',
+  'UnitSexBase',
+  'UnitIsCharmed',
+  'UnitIsPossessed',
+]);
+
+/**
+ * Literal unit tokens that keep identity APIs non-secret. The 12.1 notes state it for
+ * UnitIsCharmed/UnitIsPossessed ("no longer return secret values if the unit token passed
+ * is 'player', 'pet', or 'vehicle'"); for the rest only "player" is exempted, because the
+ * change exists to stop addons comparing secret units and a unit is never secret to itself.
+ */
+export const SELF_EXEMPT_TOKENS = new Set(['player', 'pet', 'vehicle']);
+export const AURA_STATE_IDENTITY_APIS = new Set(['UnitIsCharmed', 'UnitIsPossessed']);
+
+/** Operator findings on a categorised taint report as the 12.1 rule instead. */
+export const CATEGORY_RULES = { aura: 'WSL012', identity: 'WSL013' };
+
+/** Iterating a secret vector cannot work; flagged for categorised taints only. */
+export const ITERATORS = new Set(['pairs', 'ipairs', 'next', 'unpack']);
+
+export const AURA_SUGGESTION =
+  'show auras with an AuraContainer (AddAuraGroup/AddAuraSlot) instead';
+
+/** Calls removed, renamed or deprecated in 12.1, with the replacement each message names. */
+export const REMOVED_CALLS = {
+  UIParentLoadAddOn: {
+    ruleId: 'WSL014',
+    message: 'UIParentLoadAddOn() was renamed in 12.1; call LoadAddOnWithErrorHandling() instead',
+  },
+  CanAccessObject: {
+    ruleId: 'WSL014',
+    message: 'CanAccessObject() was removed in 12.1; use FrameScriptObject:CanBeAccessedInContext() instead',
+  },
+  'C_UnitAuras.TriggerPrivateAuraShowDispelType': {
+    ruleId: 'WSL014',
+    message:
+      'C_UnitAuras.TriggerPrivateAuraShowDispelType() was removed in 12.1; use the showDispelIcon option on private aura anchors instead',
+  },
+  getglobal: {
+    ruleId: 'WSL015',
+    message: 'getglobal() is deprecated in 12.1; use _G[name] instead',
+  },
+  setglobal: {
+    ruleId: 'WSL015',
+    message: 'setglobal() is deprecated in 12.1; use _G[name] = value instead',
+  },
+};
+
+export const REMOVED_TEMPLATE = 'SecureAuraHeaderTemplate';
+export const REMOVED_TEMPLATE_MESSAGE =
+  'SecureAuraHeaderTemplate was removed from Mainline in 12.1; migrate to an AuraContainer (AddAuraGroup/AddAuraSlot)';
+
+/** Structure fields renamed in 12.1 whose old name is silently ignored at runtime. */
+export const RENAMED_STRUCT_FIELDS = {
+  showCountdownFrame: 'showCooldownFrame',
+};
+
+/** CreateFrame frame types that carry Forbidden Aspects from creation. */
+export const ASPECT_FRAME_TYPES = new Set(['AuraContainer', 'AuraButton']);
+
+/** Container methods whose options table hands AuraButtons to an initializeFrame callback. */
+export const AURA_GROUP_METHODS = new Set(['AddAuraGroup', 'AddAuraSlot', 'AddItemEnchantment']);
+
+/**
+ * Methods disallowed by the Forbidden Aspects each frame type carries. Buttons additionally
+ * get event registration flagged: they join the container's forbidden partition and the 12.1
+ * announcement says addons cannot "register events on those buttons".
+ */
+const BUTTON_SCRIPTS = { aspect: 'UntrustedScriptExecution', verb: 'installing a script handler' };
+const EVENT_REG = { aspect: 'EventRegistrations', verb: 'registering for events' };
+const INPUT_CALL = { aspect: 'ScriptedInput', verb: 'calling an input API' };
+const FOCUS_QUERY = { aspect: 'QueryFocus', verb: 'querying focus' };
+
+export const FORBIDDEN_ASPECT_METHODS = {
+  AuraButton: {
+    SetScript: BUTTON_SCRIPTS,
+    HookScript: BUTTON_SCRIPTS,
+    RegisterEvent: EVENT_REG,
+    RegisterUnitEvent: EVENT_REG,
+    RegisterAllEvents: EVENT_REG,
+    Click: INPUT_CALL,
+    SetFocus: INPUT_CALL,
+    EnableMouse: INPUT_CALL,
+    EnableKeyboard: INPUT_CALL,
+    EnableMouseWheel: INPUT_CALL,
+    EnableGamePadButton: INPUT_CALL,
+    EnableGamePadStick: INPUT_CALL,
+    SetPropagateKeyboardInput: INPUT_CALL,
+    SetPassThroughButtons: INPUT_CALL,
+    RegisterForClicks: INPUT_CALL,
+    RegisterForDrag: INPUT_CALL,
+    IsMouseOver: FOCUS_QUERY,
+    IsMouseMotionFocus: FOCUS_QUERY,
+    HasFocus: FOCUS_QUERY,
+  },
+  AuraContainer: {
+    RegisterEvent: EVENT_REG,
+    RegisterUnitEvent: EVENT_REG,
+    RegisterAllEvents: EVENT_REG,
+  },
+};
+
 /**
  * Decide how a boolean test on a secret should be reported.
  * Returns 'error' when the documented type is bool, null when it is a documented non-bool