From c7a2c4a713589e23d3feeb89de201c25af76007a Mon Sep 17 00:00:00 2001 From: Dusk-92 Date: Sun, 30 Aug 2026 10:39:19 +0200 Subject: [PATCH] Document second full counter-audit --- AUDIT.md | 226 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) diff --git a/AUDIT.md b/AUDIT.md index 39bf0f7..9812458 100644 --- a/AUDIT.md +++ b/AUDIT.md @@ -8,6 +8,232 @@ This document records the static audit performed on the fork. Runtime behavior still requires in-game validation because the WoW 1.12 UI runtime cannot be executed in GitHub. +## Second full counter-audit — 2026-08-30 + +A second audit was performed from the current branch state without assuming the +first audit was correct. This pass rechecked every retained module, cross-checked +the current ShaguTweaks-ClassicAPI tree, and specifically looked for load-order +bugs, stale UI state, first-frame initialization issues, hook ordering, +configuration interactions and unnecessary polling. + +### Counter-audit result + +**Static status: PASS with raid runtime validation still pending.** + +The branch currently contains **23 Extras modules**. The current main +ShaguTweaks-ClassicAPI fork contains **48 modules**. The duplicate review was +repeated against the current main tree and did not reveal any additional module +that should be removed. Chat History and Energy Tick remain the only two +intentional duplicate removals. + +The addon TOC references **32 Lua files and all 32 exist**. The four bundled TGA +assets used by retained modules are present, the eight locale files are harmless +empty stubs, and the original MIT license remains intact. + +### New issues found and fixed during the second audit + +#### Unordered ShaguTweaks module initialization + +ShaguTweaks enables registered modules by iterating its module table with +`pairs()`, so module enable order must never be assumed. + +The second audit found several hidden order dependencies: + +- **Use As Party Frames** could return permanently when the base raid frame had + not been enabled yet. +- **Hide Party Frames** had the same dependency. +- **Use Compact Layout** could access `ShaguTweaksRaidCluster.config` before + the cluster existed. +- **Show Bags** and **Show Micro Menu** could read an uninitialized + `Reduced Actionbar Size` configuration key on a fresh installation. + +The raid core now exposes `ShaguTweaks.RaidFrame_OnReady(callback)`. Raid +submodules queue their initialization until the base raid frame exists, while +still executing immediately when it is already ready. + +The reduced-actionbar companion modules now fall back to the main module's +declared default when its saved configuration key has not yet been initialized. + +#### Raid component ordering + +Ordered component and event lists now use `ipairs()` where order matters. +Base raid components are therefore always created in their defined order before +dependent Extras components such as Compact Layout, Combat Feedback and +Healing Predictions. + +#### Deterministic first raid-frame state + +Raid unit frames are created during `PLAYER_ENTERING_WORLD`. A newly-created +frame cannot safely rely on receiving the same event that caused it to be +created. + +The base raid module now provides `ShaguTweaks.UnitFrame_Refresh(frame)` and +explicitly refreshes a frame immediately after assigning its raid/party unit. + +Initial visual states are also explicit: + +- target marker starts hidden +- combat highlight starts hidden +- aggro indicator starts hidden +- dispel indicators start hidden +- healing prediction starts hidden + +This removes transient default-state artifacts while waiting for the next unit +event. + +#### Raid group headers + +Group Headers previously depended on receiving an event after their container +was created. The header module now waits only until all 40 raid-frame anchor +objects exist, performs an explicit first update, and then removes its temporary +`OnUpdate`. + +It also updates on party changes so it behaves correctly when Raid Frames are +used as party frames. + +Compact Layout no longer waits forever when Group Headers are disabled. When +headers are enabled it waits for an actual child header, not merely the header +container, and has a ten-second safety timeout. + +#### Hide Party Frames visibility + +Default PartyFrames are now hidden only while both the custom raid frame and +its cluster are visible. If the user manually hides the custom raid cluster, +the original PartyFrame `Show` methods are restored rather than leaving both +UIs hidden. + +#### Healing prediction width + +Incoming-heal width is recalculated on every shared 250 ms prediction tick +while a heal is active. Previously the width changed only when the incoming +heal amount changed, so player health changes could leave the predicted bar at +a stale width. + +#### Reagent Counter stale slots + +A slot that changed directly from a reagent-using spell to a non-reagent action +could retain its old reagent association. Full actionbar rescans now rebuild +the active reagent set, and occupied slots explicitly clear their previous +reagent when the tooltip contains no reagent requirement. + +#### Floating Actionbar reputation anchors + +`ReputationWatchBar` now clears its existing anchors before changing between +the XP-visible and XP-hidden positions. This prevents multiple constraints from +accumulating after reputation/XP state changes. + +#### Chat wrapper ordering + +**Chat Timestamps** and the main fork's **Chat Tweaks** both wrap +`ChatFrame.AddMessage`. Because module enable order is unordered, their wrapper +order could previously change between sessions. + +Timestamp wrapping is now installed at `PLAYER_ENTERING_WORLD`, after the +normal ShaguTweaks module pass, giving a deterministic wrapper chain. + +**Center Text Input Box** now uses the same strategy for its +`UIParent_ManageFramePositions` post-hook. This ensures it calculates its +position after Reduced Actionbar and other main-fork layout hooks have already +been installed. + +#### Macro command ownership + +`/equip` and `/use` now use the same collision-safe registration helper as +`/startattack`, `/stopattack`, `/focus` and `/clearfocus`. Macro Tweaks +therefore does not steal a slash command already registered by another addon. + +#### World Map reveal state + +The second pass removed dead overlay-hash/cache state that was not used to +render or compare map tiles. + +Exploration marker frames now clear their previous anchors before being reused +on another zone map, and anonymous textures are used instead of empty-string +global texture names. Known native overlays are represented as simple boolean +membership data. + +The current main fork's WorldMap Window, WorldMap Coordinates and WorldMap +Class Colors modules were cross-checked and do not replace +`WorldMapFrame_Update`, so they can coexist with Reveal World Map's safe +pre/post hooks. + +### Configuration interaction review + +- **Hide Gryphons + Dragonflight Gryphons:** safe. Hide Gryphons takes + precedence because Dragonflight Gryphons changes textures but never forces a + hidden endcap to show. +- **Floating Actionbar + Reduced Actionbar Size:** compatible. Their shared + reputation/actionbar layout interaction is now anchor-safe. +- **Show Bags / Show Micro Menu + Reduced Actionbar Size:** intentionally + coupled. The Extras modules restore the native `Show` method that Reduced + Actionbar deliberately suppresses, then reparent those controls to their own + panels. + +### Remaining intentional global wrappers + +The second audit again reviewed every remaining direct wrapper. These are kept +because the feature must intercept rather than merely observe the call: + +- `UseContainerItem` — Bag Item Click can redirect the action to trade/AH. +- `SendChatMessage` — Macro Tweaks suppresses `#showtooltip` metadata that + Vanilla would otherwise send to chat. +- `ChatFrameEditBox.AddHistoryLine` — prevents executed macro commands from + polluting typed-command history. +- `ChatFrame.AddMessage` — Chat Timestamps must alter displayed text. +- PartyMemberFrame `Show` — temporarily suppressed while the custom raid UI is + actually visible and restored afterwards. + +No retained module directly replaces `WorldMapFrame_Update`, +`UIParent_ManageFramePositions`, `ReputationWatchBar_Update` or +`GameTooltip.SetBagItem`. + +### Remaining OnUpdate review + +Every retained `OnUpdate` was reviewed again: + +- **Reagent Counter:** frame is hidden while idle and wakes for one processing + frame after relevant events. +- **Show Bags / Show Micro Menu:** 50 ms modifier/mouse polling used only for + the Ctrl+Shift drag interaction. +- **Raid shared ticker:** one 250 ms ticker services periodic raid components. +- **Raid toggle drag:** installed only while the user is actively dragging. +- **Group Headers:** temporary one-shot initialization waiter, removed as soon + as all raid anchors exist. +- **Compact Layout:** temporary header waiter with a ten-second hard stop. +- **Combat Feedback:** per-visible-unit frame animation remains intentionally + unchanged pending real raid profiling. + +### Runtime-only risks still open + +Two areas require a real populated raid before they should be optimized further: + +1. **Combat Feedback** uses Blizzard's `CombatFeedback_OnUpdate` animation and + therefore retains per-visible-unit frame updates. Replacing that animation + without runtime testing would be higher risk than leaving it intact. +2. **Aggro Indicator** uses a Vanilla-compatible heuristic that checks targets + and target-of-target relationships across group/raid unit tokens. It is + cached for one second per displayed unit, but a 20/40-player raid is still + required to measure its actual cost. + +These are not currently identified correctness bugs. They are explicit +performance validation targets. + +### Current runtime validation status + +Macro Tweaks / Macro Icons received live fixes and retesting for: + +- `/startattack` +- bare `#showtooltip` +- `#showtooltip Spell` +- automatic macro spell icon resolution + +Those cases are now behaving correctly in the test client. + +Raid functionality remains **runtime-unvalidated**. The branch should therefore +stay a draft test candidate until at least a small converted raid has exercised +frame creation, roster changes, party-frame restoration, dispels, predictions +and combat feedback. + ## Scope The upstream fork contained **25 Lua modules**. Two are duplicates of features