forever-lint 0.1.0__tar.gz

forever_lint-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+vendor/
+*.sarif
+summary.txt
+.index-cache/
+site/

forever_lint-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (2026-11-03)
+
+First release, against WoW Forever 1.60.1 (70532) and its UI source 1.60.1 (70755).
+
+- Rules from the 1.60.1 API notes (warcraft.wiki, Oct 2026): `require` renamed to `import` (FL001), `GetFrameStrata` secret values (FL003), SAY/YELL/EMOTE hardware events (FL011), trial accounts and addon messages (FL012).
+- Rules FL001–FL010: removed and deprecated API, secret values, `WOW_PROJECT_ID`, `GetBuildInfo` version checks, removed and restricted events, TOC selection, interface version and game-type exclusions.
+- Follows the TOC Forever loads (game-type suffixes, per-file directives, XML includes).
+- Scope-aware analysis with polyfill, guard and checked-replacement detection.
+- Text, JSON and SARIF output; `--explain`; inline suppressions; GitHub Action.

forever_lint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Argento
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forever_lint-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: forever-lint
+Version: 0.1.0
+Summary: Checks World of Warcraft addons for problems on WoW Forever: removed API, secret values, project ID checks, events and TOC files.
+Project-URL: Homepage, https://github.com/JoseArgento/forever-lint
+Project-URL: Issues, https://github.com/JoseArgento/forever-lint/issues
+Author: José Argento
+License-Expression: MIT
+License-File: LICENSE
+Keywords: addon,lint,lua,sarif,static-analysis,world-of-warcraft,wow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Lua
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# forever-lint
+
+Checks World of Warcraft addons for problems on **WoW Forever**, before your users find them.
+
+Forever looks like Classic but runs the modern client: Classic-era version numbers on top of the retail API, with Midnight's addon restrictions. Code written for Classic Era breaks in ways that are easy to miss: `GetSpellInfo` is gone, `WOW_PROJECT_ID` is neither Classic nor retail, health values can be secret, and an addon with only a `_Vanilla.toc` does not load at all.
+
+```
+$ forever-lint MyAddon
+forever-lint 0.1.0 · WoW Forever 1.60.1 (70532), interface 16001
+
+MyAddon  (MyAddon, MyAddon.toc, 2 Lua files)
+  warning FL009 MyAddon.toc declares Interface 11509, 120105 but Forever is 16001: the addon shows as out of date ...
+
+MyAddon/Core.lua
+  2:22  error FL001 `GetSpellInfo` does not exist in Forever. Probably replaced by `C_Spell.GetSpellInfo`. Note: `C_Spell.GetSpellInfo` returns a SpellInfo table, not separate values.
+  4:19  warning FL004 In Forever `WOW_PROJECT_ID` is 18 (`WOW_PROJECT_CAMELOT`), so `WOW_PROJECT_ID == WOW_PROJECT_CLASSIC` is false. ...
+  10:10  warning FL003 `hp` holds the result of `UnitHealth`, which can return a secret value in Forever (always). ...
+  14:17  warning FL006 Event `COMBAT_LOG_EVENT_UNFILTERED`: the combat log is restricted for addons in Forever ...
+  18:16  error FL001 `GetItemInfo` does not exist in Forever. Use `C_Item.GetItemInfo`.
+
+8 errors, 6 warnings, 1 note in 1 addon(s)
+```
+
+[Leer en castellano](README.es.md)
+
+## Install
+
+```bash
+pip install forever-lint      # Python 3.10+, no dependencies
+forever-lint path/to/MyAddon   # one addon, a repo with several, or your whole AddOns folder
+```
+
+## What it checks
+
+| Rule | Severity | What |
+|---|---|---|
+| <a id="fl001-removed-api"></a>**FL001** removed-api | error | A function, namespace or Blizzard UI function that does not exist in Forever, with its replacement when there is one. Also `hooksecurefunc("Name", ...)` on a missing global, which raises an error. |
+| <a id="fl002-deprecated-api"></a>**FL002** deprecated-api | warning | API that only exists as one of Blizzard's deprecation fallbacks (loaded while the `loadDeprecationFallbacks` CVar is on). Blizzard says these will be removed. |
+| <a id="fl003-secret-value"></a>**FL003** secret-value | warning | Arithmetic or comparisons on the result of a function documented to return secret values (`UnitHealth`, `UnitPower` when restricted, `frame:GetFrameStrata()` since 1.60.1, ...). In addon code that raises a Lua error. |
+| <a id="fl004-project-id"></a>**FL004** project-id | warning | `WOW_PROJECT_ID` comparisons, with what they evaluate to in Forever (18, `WOW_PROJECT_CAMELOT`). Lines that already mention `WOW_PROJECT_CAMELOT` are notes. |
+| <a id="fl005-removed-event"></a>**FL005** removed-event | error | `RegisterEvent("EVENT")` for an event Forever does not have. |
+| <a id="fl006-restricted-event"></a>**FL006** restricted-event | warning | Events with restrictions or secret payloads, such as `COMBAT_LOG_EVENT_UNFILTERED`. |
+| <a id="fl007-build-version"></a>**FL007** build-version | warning | `select(4, GetBuildInfo())` checks: Forever reports 16001, so "modern client" tests like `>= 100000` are false. |
+| <a id="fl008-no-forever-toc"></a>**FL008** no-forever-toc | error | No TOC that Forever loads. It looks for `_Camelot`, `_Forever`, `_Mainline`, then the plain `.toc`. |
+| <a id="fl009-toc-interface"></a>**FL009** toc-interface | warning | The TOC's `## Interface:` does not list 16001, so the addon shows as out of date. |
+| <a id="fl010-toc-game-type"></a>**FL010** toc-game-type | note | The TOC excludes Forever with `AllowLoadGameType`/`ExcludeLoadGameType`. Fine if on purpose. |
+| <a id="fl011-chat-hardware-event"></a>**FL011** chat-hardware-event | note | `SendChatMessage` with SAY, YELL or EMOTE: outside instances it needs a key press or click (EMOTE since 1.60.1). Inside instances a beta tester reported it no longer works at all (18/10, not confirmed). |
+| <a id="fl012-trial-addon-messages"></a>**FL012** trial-addon-messages | note | Trial accounts cannot send addon messages (1.60.1). Reported once per addon. |
+| <a id="fl013-beta-event-quirk"></a>**FL013** beta-event-quirk | note | Events an addon author reported behave differently in Forever's beta (18/10, not confirmed): `PLAYER_DEAD` and the `MERCHANT_CLOSED`/`AUCTION_HOUSE_CLOSED` pair fire twice, and the zone text right after `ZONE_CHANGED_NEW_AREA` can be stale or empty after travelling. |
+
+It follows the TOC Forever would pick, including `[AllowLoadGameType ...]` per file and the `<Script>`/`<Include>` files of XML, so code for other clients is not reported. `--all-files` checks every `.lua` file instead.
+
+### Fewer false positives
+
+The analysis tracks Lua scopes, so a local or parameter called `GetSpellInfo` is not reported. It also recognises the usual multi-client patterns:
+
+- **Polyfills**: if the addon assigns the global itself (`GetSpellInfo = GetSpellInfo or function ...`), uses anywhere in the addon are fine.
+- **Guards**: `if GetMouseFocus then`, `GetMouseFocus and ...`, `C_X and C_X.Y or Old` become notes, because the fallback branch is the one that runs in Forever.
+- **Checked replacement**: `if C_Item and C_Item.GetItemSpell then return C_Item.GetItemSpell(id) end return GetItemSpell(id)` is a note. Forever has the new function, so the old line does not run there.
+- **Embedded libraries** (`Libs/`, `lib/`, ...) are summarised, never fail the run, and are listed with `--libs`.
+
+### Silencing a finding
+
+```lua
+local x = GetMouseFocus() -- forever-lint: ignore FL001
+-- forever-lint: ignore-next-line
+OldThing()
+-- forever-lint: ignore-file
+```
+
+Or skip whole rules with `--ignore FL002,FL004`.
+
+## With luacheck or pre-commit
+
+`forever-lint --export-luacheck > .luacheckrc.forever` prints a `read_globals` block with every function Forever has (deprecation fallbacks left out), to paste into an existing `.luacheckrc`.
+
+For [pre-commit](https://pre-commit.com):
+
+```yaml
+repos:
+  - repo: https://github.com/JoseArgento/forever-lint
+    rev: v0.1.0
+    hooks:
+      - id: forever-lint
+```
+
+## Options
+
+```
+forever-lint PATH... [--format text|json|sarif] [-o FILE] [--fail-on error|warning|note|never]
+                     [--ignore RULES] [--libs] [--all-files] [--no-color]
+forever-lint --explain GetSpellInfo     # what Forever has for a name
+forever-lint --list-rules
+```
+
+The exit code is 1 when there is a finding at the `--fail-on` severity (default `error`) outside libraries.
+
+## In CI (GitHub Actions)
+
+Findings show up as code scanning annotations on the pull request:
+
+```yaml
+jobs:
+  forever:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JoseArgento/forever-lint@v0
+        with:
+          path: .
+          fail-on: error
+```
+
+Without the action: `pip install forever-lint && forever-lint . --format sarif -o forever-lint.sarif`, then upload the file with `github/codeql-action/upload-sarif`.
+
+## Compatibility index
+
+`index/` builds a static site that runs forever-lint over popular addons with public GitHub repositories (`index/addons.json`) and publishes the results with GitHub Pages every week. It shows file, line and message for every finding, never the addons' code. To add an addon, open a pull request with its repository in `index/addons.json`.
+
+```bash
+python index/build_index.py --cache .index-cache --out site   # then open site/index.html
+python index/build_api.py --out site                          # site/api.html: every Classic API that moved
+```
+
+The same site has an **API migration table** (`api.html`, also as `api.json`): every function that existed in a Classic client and is missing, moved or restricted in Forever, with its replacement, plus the deprecation fallbacks, secret-value functions and events. An addon author asked for exactly this list in the Forever beta feedback thread.
+
+**"Now works on Forever" feed.** Every week the index is compared with the previous one, and the addons that got better (from "does not load" to "loads", or from errors to clean) go into an RSS feed at `feed.xml` on the same site. Links open that addon's row. To also post them to a Telegram channel, create a bot with @BotFather, add it to the channel, and set `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` as repository secrets; without them the step is skipped.
+
+## Where the data comes from
+
+Everything in `src/forever_lint/data/api.json` is generated by `tools/build_db.py` from public data, and a weekly workflow rebuilds it when Blizzard patches Forever:
+
+- **What exists in Forever and other clients**: the global and namespace API dumped from the running clients by [Ketho/BlizzardInterfaceResources](https://github.com/Ketho/BlizzardInterfaceResources) (branches `forever`, `classic_era`, `classic`, `classic_anniversary`, `live`, dumped with deprecation fallbacks off), plus every name that appeared in its history since 2019, for APIs older addons still call.
+- **Deprecation fallbacks, replacements and secret values**: Blizzard's own UI source as mirrored by [Gethe/wow-ui-source](https://github.com/Gethe/wow-ui-source). That covers the `Blizzard_Deprecated*` addons (which ones load for Forever's game type, and whether their target exists: `CombatLogGetCurrentEventInfo` points to a function addons cannot use), the 11.0 spell API transition guide, and `Blizzard_APIDocumentationGenerated` for `SecretReturns`, `SecretWhen*`, restricted events and structure return types.
+- **TOC rules**: [warcraft.wiki.gg TOC format](https://warcraft.wiki.gg/wiki/TOC_format).
+- A short list of replacements that cannot be derived (`GetMouseFocus` → `GetMouseFoci`, `EasyMenu` → `MenuUtil.CreateContextMenu`, ...) lives in `tools/curated.json`. Each target is checked against Forever when the database is built.
+
+Only API names and flags are shipped. No Blizzard code is included.
+
+## Limitations
+
+- It is a lexical analysis, not an interpreter. It cannot tell which side of `if isClassic then ... else ... end` runs in Forever, so code in a branch for another client is still reported. Use the guard patterns above, an inline `ignore`, or the TOC's `[AllowLoadGameType]` to keep that code out of Forever.
+- "Probably replaced by" means the replacement was matched by name (`GetAddOnMetadata` → `C_AddOns.GetAddOnMetadata`). Check its arguments and return values; many `C_` functions return a table.
+- Widget methods (`frame:SetBackdrop`) and global constants are not checked yet.
+- Events are read from string literals (`RegisterEvent("PLAYER_DEAD")`) and, when a file registers events from a variable (`for event in pairs(handlers) do frame:RegisterEvent(event) end`), from the keys of its handler tables (`PLAYER_DEAD = function`). Events built at runtime (`"UNIT_" .. kind`) are not followed.
+- Secret values are flagged when the value is used directly, or through a local in the same file, in arithmetic or a comparison. Cached globals (`local UnitHealth = UnitHealth`) count. A check on the same line (`issecretvalue(hp) or`, `E:NotSecretValue(hp) and`) counts as a guard; a check on an earlier line does not. Values passed through tables or other functions are not followed.
+
+## Tested on
+
+Questie, Details!, Bartender4, BigWigs and Deadly Boss Mods (November 2026 versions). Questie and Details already ship a `_Camelot.toc`. The few errors left in them are calls to missing APIs in code that Forever's TOC loads.
+
+## Support
+
+forever-lint is free and open source. Not affiliated with or endorsed by Blizzard Entertainment. World of Warcraft is a trademark of Blizzard Entertainment, Inc.
+
+## License
+
+MIT

forever_lint-0.1.0/README.es.md

@@ -0,0 +1,84 @@
+# forever-lint
+
+Revisa addons de World of Warcraft y encuentra lo que se rompe en **WoW Forever**, antes de que lo encuentren tus usuarios.
+
+Forever parece Classic, pero corre el cliente moderno: números de versión de Classic sobre la API de retail, con las restricciones a addons de Midnight. El código hecho para Classic Era se rompe de formas fáciles de pasar por alto:
+- `GetSpellInfo` ya no existe;
+- `WOW_PROJECT_ID` no es ni Classic ni retail;
+- la vida puede llegar como valor secreto;
+- y un addon que solo trae `_Vanilla.toc` directamente no carga.
+
+[Read in English](README.md)
+
+## Instalar y usar
+
+```bash
+pip install forever-lint      # Python 3.10+, sin dependencias
+forever-lint ruta/a/MiAddon    # un addon, un repo con varios, o la carpeta AddOns entera
+```
+
+## Qué revisa
+
+| Regla | Severidad | Qué |
+|---|---|---|
+| **FL001** | error | Función, namespace o función de la UI de Blizzard que no existe en Forever, con su reemplazo cuando lo hay. También `hooksecurefunc("Nombre", ...)` sobre una global que no existe, que tira error. |
+| **FL002** | warning | API que solo existe como alias de compatibilidad de Blizzard (mientras el CVar `loadDeprecationFallbacks` está prendido). Blizzard avisa que los va a sacar. |
+| **FL003** | warning | Cuentas o comparaciones con lo que devuelve una función documentada como "secret" (`UnitHealth`, `UnitPower` en ciertos casos...). En un addon eso tira un error de Lua. |
+| **FL004** | warning | Comparaciones con `WOW_PROJECT_ID`, con lo que dan en Forever (18, `WOW_PROJECT_CAMELOT`). |
+| **FL005** | error | `RegisterEvent("EVENTO")` de un evento que Forever no tiene. |
+| **FL006** | warning | Eventos restringidos o con payload secreto, como `COMBAT_LOG_EVENT_UNFILTERED`. |
+| **FL007** | warning | Chequeos de `select(4, GetBuildInfo())`: Forever reporta 16001, así que `>= 100000` da falso. |
+| **FL008** | error | No hay un TOC que Forever cargue (busca `_Camelot`, `_Forever`, `_Mainline` y después el `.toc` sin sufijo). |
+| **FL009** | warning | El `## Interface:` del TOC no incluye 16001, así que el addon aparece como desactualizado. |
+| **FL010** | nota | El TOC excluye a Forever con `AllowLoadGameType`/`ExcludeLoadGameType`. Está bien si es a propósito. |
+| **FL011** | nota | `SendChatMessage` con SAY, YELL o EMOTE: fuera de instancias necesita que el jugador apriete algo (EMOTE desde 1.60.1). Dentro de instancias, un tester de la beta reportó que ya no anda (18/10, sin confirmar). |
+| **FL012** | nota | Las cuentas de prueba no pueden mandar mensajes de addon (1.60.1). Sale una vez por addon. |
+| **FL013** | nota | Eventos que, según un autor de addons en la beta (18/10, sin confirmar), se comportan distinto en Forever: `PLAYER_DEAD` y `MERCHANT_CLOSED`/`AUCTION_HOUSE_CLOSED` saltan dos veces, y la zona justo después de `ZONE_CHANGED_NEW_AREA` puede venir vieja o vacía al viajar. |
+
+Revisa solo los archivos que carga el TOC que elige Forever (incluyendo `[AllowLoadGameType]` por archivo y los `<Script>`/`<Include>` de los XML). Así no reporta código de otros clientes.
+
+Para no llenarte de falsos positivos:
+- sigue los alcances de Lua, así que un `local GetSpellInfo` no salta;
+- reconoce los polyfills (`GetSpellInfo = GetSpellInfo or function ...`);
+- los guards (`if GetMouseFocus then`) salen como notas;
+- también es nota el fallback que viene después de chequear el reemplazo (`if C_Item and C_Item.GetItemSpell then ... end return GetItemSpell(id)`);
+- las librerías embebidas (`Libs/`) salen resumidas y nunca hacen fallar la corrida.
+
+Silenciar: `-- forever-lint: ignore FL001` en la línea, `-- forever-lint: ignore-next-line`, `-- forever-lint: ignore-file`, o `--ignore FL002,FL004`.
+
+## En CI
+
+```yaml
+      - uses: JoseArgento/forever-lint@v0
+        with:
+          path: .
+```
+
+Sube un SARIF a code scanning, así los hallazgos aparecen como anotaciones en el pull request (hace falta `security-events: write`).
+
+## Índice de compatibilidad
+
+`index/` arma una web estática: corre forever-lint sobre addons populares con repo público en GitHub (`index/addons.json`) y la publica en GitHub Pages cada semana. Muestra archivo, línea y mensaje de cada hallazgo, nunca el código de los addons. Para sumar un addon, abrí un pull request con su repo en `index/addons.json`.
+
+La misma web tiene una **tabla de API movida** (`api.html`, también como `api.json`): cada función que existía en algún Classic y en Forever no está, se movió o está restringida, con su reemplazo, más los alias de compatibilidad, los valores secretos y los eventos.
+
+## De dónde salen los datos
+
+`tools/build_db.py` arma `src/forever_lint/data/api.json`, y un workflow semanal lo regenera cuando Blizzard parchea Forever:
+- La API que existe en cada cliente sale de los dumps de [Ketho/BlizzardInterfaceResources](https://github.com/Ketho/BlizzardInterfaceResources), con su historial desde 2019.
+- Los alias de compatibilidad, los reemplazos, los valores secretos y los eventos restringidos salen del código de la UI de Blizzard (espejo [Gethe/wow-ui-source](https://github.com/Gethe/wow-ui-source)), incluida `Blizzard_APIDocumentationGenerated`.
+
+Solo se publican nombres y flags; nada de código de Blizzard.
+
+## Feed "ya anda en Forever"
+
+Cada semana el índice se compara con el anterior, y los addons que mejoraron (de "no carga" a "carga", o de errores a limpio) salen en un feed RSS, `feed.xml`, en el mismo sitio. Para mandarlos también a un canal de Telegram: creá un bot con @BotFather, sumalo al canal y cargá `TELEGRAM_BOT_TOKEN` y `TELEGRAM_CHAT_ID` como secretos del repo. Sin ellos ese paso no corre.
+
+## Límites
+
+- Es análisis léxico: no sabe qué rama de un `if esClassic then ... else ... end` corre en Forever.
+- "Probably replaced by" es un reemplazo encontrado por nombre. Revisá argumentos y retornos (muchas `C_` devuelven una tabla).
+- Todavía no revisa métodos de widgets ni constantes globales.
+- Los eventos los lee de textos fijos (`RegisterEvent("PLAYER_DEAD")`) y, si un archivo los registra desde una variable (`for event in pairs(handlers) do frame:RegisterEvent(event) end`), de las claves de sus tablas de manejadores (`PLAYER_DEAD = function`). Los que se arman al correr (`"UNIT_" .. tipo`) no los sigue.
+
+Sin relación con Blizzard Entertainment. World of Warcraft es marca registrada de Blizzard Entertainment, Inc. Licencia MIT.

forever_lint-0.1.0/README.md

@@ -0,0 +1,161 @@
+# forever-lint
+
+Checks World of Warcraft addons for problems on **WoW Forever**, before your users find them.
+
+Forever looks like Classic but runs the modern client: Classic-era version numbers on top of the retail API, with Midnight's addon restrictions. Code written for Classic Era breaks in ways that are easy to miss: `GetSpellInfo` is gone, `WOW_PROJECT_ID` is neither Classic nor retail, health values can be secret, and an addon with only a `_Vanilla.toc` does not load at all.
+
+```
+$ forever-lint MyAddon
+forever-lint 0.1.0 · WoW Forever 1.60.1 (70532), interface 16001
+
+MyAddon  (MyAddon, MyAddon.toc, 2 Lua files)
+  warning FL009 MyAddon.toc declares Interface 11509, 120105 but Forever is 16001: the addon shows as out of date ...
+
+MyAddon/Core.lua
+  2:22  error FL001 `GetSpellInfo` does not exist in Forever. Probably replaced by `C_Spell.GetSpellInfo`. Note: `C_Spell.GetSpellInfo` returns a SpellInfo table, not separate values.
+  4:19  warning FL004 In Forever `WOW_PROJECT_ID` is 18 (`WOW_PROJECT_CAMELOT`), so `WOW_PROJECT_ID == WOW_PROJECT_CLASSIC` is false. ...
+  10:10  warning FL003 `hp` holds the result of `UnitHealth`, which can return a secret value in Forever (always). ...
+  14:17  warning FL006 Event `COMBAT_LOG_EVENT_UNFILTERED`: the combat log is restricted for addons in Forever ...
+  18:16  error FL001 `GetItemInfo` does not exist in Forever. Use `C_Item.GetItemInfo`.
+
+8 errors, 6 warnings, 1 note in 1 addon(s)
+```
+
+[Leer en castellano](README.es.md)
+
+## Install
+
+```bash
+pip install forever-lint      # Python 3.10+, no dependencies
+forever-lint path/to/MyAddon   # one addon, a repo with several, or your whole AddOns folder
+```
+
+## What it checks
+
+| Rule | Severity | What |
+|---|---|---|
+| <a id="fl001-removed-api"></a>**FL001** removed-api | error | A function, namespace or Blizzard UI function that does not exist in Forever, with its replacement when there is one. Also `hooksecurefunc("Name", ...)` on a missing global, which raises an error. |
+| <a id="fl002-deprecated-api"></a>**FL002** deprecated-api | warning | API that only exists as one of Blizzard's deprecation fallbacks (loaded while the `loadDeprecationFallbacks` CVar is on). Blizzard says these will be removed. |
+| <a id="fl003-secret-value"></a>**FL003** secret-value | warning | Arithmetic or comparisons on the result of a function documented to return secret values (`UnitHealth`, `UnitPower` when restricted, `frame:GetFrameStrata()` since 1.60.1, ...). In addon code that raises a Lua error. |
+| <a id="fl004-project-id"></a>**FL004** project-id | warning | `WOW_PROJECT_ID` comparisons, with what they evaluate to in Forever (18, `WOW_PROJECT_CAMELOT`). Lines that already mention `WOW_PROJECT_CAMELOT` are notes. |
+| <a id="fl005-removed-event"></a>**FL005** removed-event | error | `RegisterEvent("EVENT")` for an event Forever does not have. |
+| <a id="fl006-restricted-event"></a>**FL006** restricted-event | warning | Events with restrictions or secret payloads, such as `COMBAT_LOG_EVENT_UNFILTERED`. |
+| <a id="fl007-build-version"></a>**FL007** build-version | warning | `select(4, GetBuildInfo())` checks: Forever reports 16001, so "modern client" tests like `>= 100000` are false. |
+| <a id="fl008-no-forever-toc"></a>**FL008** no-forever-toc | error | No TOC that Forever loads. It looks for `_Camelot`, `_Forever`, `_Mainline`, then the plain `.toc`. |
+| <a id="fl009-toc-interface"></a>**FL009** toc-interface | warning | The TOC's `## Interface:` does not list 16001, so the addon shows as out of date. |
+| <a id="fl010-toc-game-type"></a>**FL010** toc-game-type | note | The TOC excludes Forever with `AllowLoadGameType`/`ExcludeLoadGameType`. Fine if on purpose. |
+| <a id="fl011-chat-hardware-event"></a>**FL011** chat-hardware-event | note | `SendChatMessage` with SAY, YELL or EMOTE: outside instances it needs a key press or click (EMOTE since 1.60.1). Inside instances a beta tester reported it no longer works at all (18/10, not confirmed). |
+| <a id="fl012-trial-addon-messages"></a>**FL012** trial-addon-messages | note | Trial accounts cannot send addon messages (1.60.1). Reported once per addon. |
+| <a id="fl013-beta-event-quirk"></a>**FL013** beta-event-quirk | note | Events an addon author reported behave differently in Forever's beta (18/10, not confirmed): `PLAYER_DEAD` and the `MERCHANT_CLOSED`/`AUCTION_HOUSE_CLOSED` pair fire twice, and the zone text right after `ZONE_CHANGED_NEW_AREA` can be stale or empty after travelling. |
+
+It follows the TOC Forever would pick, including `[AllowLoadGameType ...]` per file and the `<Script>`/`<Include>` files of XML, so code for other clients is not reported. `--all-files` checks every `.lua` file instead.
+
+### Fewer false positives
+
+The analysis tracks Lua scopes, so a local or parameter called `GetSpellInfo` is not reported. It also recognises the usual multi-client patterns:
+
+- **Polyfills**: if the addon assigns the global itself (`GetSpellInfo = GetSpellInfo or function ...`), uses anywhere in the addon are fine.
+- **Guards**: `if GetMouseFocus then`, `GetMouseFocus and ...`, `C_X and C_X.Y or Old` become notes, because the fallback branch is the one that runs in Forever.
+- **Checked replacement**: `if C_Item and C_Item.GetItemSpell then return C_Item.GetItemSpell(id) end return GetItemSpell(id)` is a note. Forever has the new function, so the old line does not run there.
+- **Embedded libraries** (`Libs/`, `lib/`, ...) are summarised, never fail the run, and are listed with `--libs`.
+
+### Silencing a finding
+
+```lua
+local x = GetMouseFocus() -- forever-lint: ignore FL001
+-- forever-lint: ignore-next-line
+OldThing()
+-- forever-lint: ignore-file
+```
+
+Or skip whole rules with `--ignore FL002,FL004`.
+
+## With luacheck or pre-commit
+
+`forever-lint --export-luacheck > .luacheckrc.forever` prints a `read_globals` block with every function Forever has (deprecation fallbacks left out), to paste into an existing `.luacheckrc`.
+
+For [pre-commit](https://pre-commit.com):
+
+```yaml
+repos:
+  - repo: https://github.com/JoseArgento/forever-lint
+    rev: v0.1.0
+    hooks:
+      - id: forever-lint
+```
+
+## Options
+
+```
+forever-lint PATH... [--format text|json|sarif] [-o FILE] [--fail-on error|warning|note|never]
+                     [--ignore RULES] [--libs] [--all-files] [--no-color]
+forever-lint --explain GetSpellInfo     # what Forever has for a name
+forever-lint --list-rules
+```
+
+The exit code is 1 when there is a finding at the `--fail-on` severity (default `error`) outside libraries.
+
+## In CI (GitHub Actions)
+
+Findings show up as code scanning annotations on the pull request:
+
+```yaml
+jobs:
+  forever:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JoseArgento/forever-lint@v0
+        with:
+          path: .
+          fail-on: error
+```
+
+Without the action: `pip install forever-lint && forever-lint . --format sarif -o forever-lint.sarif`, then upload the file with `github/codeql-action/upload-sarif`.
+
+## Compatibility index
+
+`index/` builds a static site that runs forever-lint over popular addons with public GitHub repositories (`index/addons.json`) and publishes the results with GitHub Pages every week. It shows file, line and message for every finding, never the addons' code. To add an addon, open a pull request with its repository in `index/addons.json`.
+
+```bash
+python index/build_index.py --cache .index-cache --out site   # then open site/index.html
+python index/build_api.py --out site                          # site/api.html: every Classic API that moved
+```
+
+The same site has an **API migration table** (`api.html`, also as `api.json`): every function that existed in a Classic client and is missing, moved or restricted in Forever, with its replacement, plus the deprecation fallbacks, secret-value functions and events. An addon author asked for exactly this list in the Forever beta feedback thread.
+
+**"Now works on Forever" feed.** Every week the index is compared with the previous one, and the addons that got better (from "does not load" to "loads", or from errors to clean) go into an RSS feed at `feed.xml` on the same site. Links open that addon's row. To also post them to a Telegram channel, create a bot with @BotFather, add it to the channel, and set `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` as repository secrets; without them the step is skipped.
+
+## Where the data comes from
+
+Everything in `src/forever_lint/data/api.json` is generated by `tools/build_db.py` from public data, and a weekly workflow rebuilds it when Blizzard patches Forever:
+
+- **What exists in Forever and other clients**: the global and namespace API dumped from the running clients by [Ketho/BlizzardInterfaceResources](https://github.com/Ketho/BlizzardInterfaceResources) (branches `forever`, `classic_era`, `classic`, `classic_anniversary`, `live`, dumped with deprecation fallbacks off), plus every name that appeared in its history since 2019, for APIs older addons still call.
+- **Deprecation fallbacks, replacements and secret values**: Blizzard's own UI source as mirrored by [Gethe/wow-ui-source](https://github.com/Gethe/wow-ui-source). That covers the `Blizzard_Deprecated*` addons (which ones load for Forever's game type, and whether their target exists: `CombatLogGetCurrentEventInfo` points to a function addons cannot use), the 11.0 spell API transition guide, and `Blizzard_APIDocumentationGenerated` for `SecretReturns`, `SecretWhen*`, restricted events and structure return types.
+- **TOC rules**: [warcraft.wiki.gg TOC format](https://warcraft.wiki.gg/wiki/TOC_format).
+- A short list of replacements that cannot be derived (`GetMouseFocus` → `GetMouseFoci`, `EasyMenu` → `MenuUtil.CreateContextMenu`, ...) lives in `tools/curated.json`. Each target is checked against Forever when the database is built.
+
+Only API names and flags are shipped. No Blizzard code is included.
+
+## Limitations
+
+- It is a lexical analysis, not an interpreter. It cannot tell which side of `if isClassic then ... else ... end` runs in Forever, so code in a branch for another client is still reported. Use the guard patterns above, an inline `ignore`, or the TOC's `[AllowLoadGameType]` to keep that code out of Forever.
+- "Probably replaced by" means the replacement was matched by name (`GetAddOnMetadata` → `C_AddOns.GetAddOnMetadata`). Check its arguments and return values; many `C_` functions return a table.
+- Widget methods (`frame:SetBackdrop`) and global constants are not checked yet.
+- Events are read from string literals (`RegisterEvent("PLAYER_DEAD")`) and, when a file registers events from a variable (`for event in pairs(handlers) do frame:RegisterEvent(event) end`), from the keys of its handler tables (`PLAYER_DEAD = function`). Events built at runtime (`"UNIT_" .. kind`) are not followed.
+- Secret values are flagged when the value is used directly, or through a local in the same file, in arithmetic or a comparison. Cached globals (`local UnitHealth = UnitHealth`) count. A check on the same line (`issecretvalue(hp) or`, `E:NotSecretValue(hp) and`) counts as a guard; a check on an earlier line does not. Values passed through tables or other functions are not followed.
+
+## Tested on
+
+Questie, Details!, Bartender4, BigWigs and Deadly Boss Mods (November 2026 versions). Questie and Details already ship a `_Camelot.toc`. The few errors left in them are calls to missing APIs in code that Forever's TOC loads.
+
+## Support
+
+forever-lint is free and open source. Not affiliated with or endorsed by Blizzard Entertainment. World of Warcraft is a trademark of Blizzard Entertainment, Inc.
+
+## License
+
+MIT

forever_lint-0.1.0/action.yml

@@ -0,0 +1,38 @@
+name: forever-lint
+description: Check World of Warcraft addons for problems on WoW Forever and upload the results to GitHub code scanning.
+branding:
+  icon: check-circle
+  color: orange
+inputs:
+  path:
+    description: Addon folder(s) to check, space separated
+    default: "."
+  fail-on:
+    description: "Fail the step at this severity or worse: error, warning, note or never"
+    default: error
+  sarif:
+    description: Upload a SARIF report to code scanning (needs security-events write permission)
+    default: "true"
+  version:
+    description: forever-lint version to install (default the latest)
+    default: ""
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - shell: bash
+      run: pip install "forever-lint${{ inputs.version && format('=={0}', inputs.version) || '' }}"
+    - shell: bash
+      run: forever-lint ${{ inputs.path }} --no-color --fail-on never
+    - if: inputs.sarif == 'true'
+      shell: bash
+      run: forever-lint ${{ inputs.path }} --format sarif --fail-on never -o forever-lint.sarif
+    - if: inputs.sarif == 'true'
+      uses: github/codeql-action/upload-sarif@v3
+      with:
+        sarif_file: forever-lint.sarif
+        category: forever-lint
+    - shell: bash
+      run: forever-lint ${{ inputs.path }} --no-color --fail-on ${{ inputs.fail-on }} > /dev/null

forever_lint-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forever-lint"
+version = "0.1.0"
+description = "Checks World of Warcraft addons for problems on WoW Forever: removed API, secret values, project ID checks, events and TOC files."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "José Argento" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["world-of-warcraft", "wow", "addon", "lua", "lint", "static-analysis", "sarif"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Lua",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Games/Entertainment",
+]
+
+[project.urls]
+Homepage = "https://github.com/JoseArgento/forever-lint"
+Issues = "https://github.com/JoseArgento/forever-lint/issues"
+
+[project.scripts]
+forever-lint = "forever_lint.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forever_lint"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tools", "tests", "README.md", "README.es.md", "LICENSE", "CHANGELOG.md", "action.yml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 140
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["E501"]

forever_lint-0.1.0/src/forever_lint/__init__.py

@@ -0,0 +1,3 @@
+"""forever-lint: checks World of Warcraft addons for problems on WoW Forever."""
+
+__version__ = "0.1.0"

forever_lint-0.1.0/src/forever_lint/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())