wow-secret-lint 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Booyaka101
+
+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.

package/README.md

@@ -0,0 +1,273 @@
+# wow-secret-lint
+
+Static analysis for World of Warcraft **retail** addons. It finds Secret Value violations in your Lua before a player finds them in a red error frame.
+
+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:
+
+> When an operation that is not allowed is performed, the result will be an **immediate** Lua error.
+
+The failure is invisible until it happens at runtime, in someone else's game, in a stack trace that points at a Blizzard file:
+
+```
+...UIWidgets/Blizzard_UIWidgetTemplateTextWithState.lua:35: attempt to perform arithmetic
+on local 'textHeight' (a secret number value, while execution tainted by 'KkthnxUI')
+```
+
+That one is [KkthnxUI#121](https://github.com/Kkthnx-Wow/KkthnxUI/issues/121), filed 2026-08-23. The identical trace was filed the same week against a completely unrelated addon, [aura-questor#68](https://github.com/lucascodev/aura-questor/issues/68). Both are in this repo's regression corpus.
+
+`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.
+
+## Install
+
+```bash
+npm install --save-dev wow-secret-lint
+# or run it once
+npx wow-secret-lint ./MyAddon
+```
+
+Node 20 or newer. No network access during a lint run: the API snapshot is vendored in the package.
+
+## Usage
+
+Point it at an addon folder and it reads the `.toc` files to decide which Lua to analyse, in load order, following `<Script>` and `<Include>` entries in any listed `.xml`.
+
+```bash
+npx wow-secret-lint ./MyAddon
+```
+
+`Core/UnitFrame.lua`:
+
+```lua
+local hp = UnitHealth("target")
+local max = UnitHealthMax("target")
+local pct = hp / max * 100
+if hp < max then frame:Show() end
+frame.text:SetText(string.format("%s hp", hp))
+```
+
+```
+$ npx wow-secret-lint Core/UnitFrame.lua
+Core/UnitFrame.lua:3:13  error  WSL001  arithmetic on a secret value: 'hp' derives from UnitHealth() (SecretReturns=true)
+Core/UnitFrame.lua:4:4   error  WSL002  comparison of a secret value: 'hp' derives from UnitHealth() (SecretReturns=true)
+2 errors, 0 warnings
+```
+
+Exit code 1. Line 5 is deliberately silent: the wiki says calling `string.format` with a secret is fine, so flagging it would be a false positive.
+
+Add the guard and it goes quiet:
+
+```lua
+if not issecretvalue(hp) and not issecretvalue(max) then
+    local pct = hp / max * 100
+    if hp < max then frame:Show() end
+end
+```
+
+```
+$ npx wow-secret-lint Core/Guarded.lua
+0 errors, 0 warnings
+```
+
+Exit code 0.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | no error-severity findings |
+| 1 | at least one error, or warnings above `--max-warnings` |
+| 2 | a file failed to parse, or a usage/runtime failure |
+
+## GitHub Action
+
+If you already run [BigWigsMods/luacheck](https://github.com/BigWigsMods/luacheck), this sits next to it. Two lines:
+
+```yaml
+jobs:
+  luacheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Luacheck linter
+        uses: BigWigsMods/luacheck@main
+        with:
+          args: -q
++     - name: Secret value linter
++       uses: Booyaka101/wow-secret-lint@v1
+```
+
+Findings render as pull request annotations on the exact line, plus a table in the job summary.
+
+Inputs:
+
+| Input | Default | Description |
+| --- | --- | --- |
+| `path` | `.` | addon folder, `.toc`, or `.lua`. Several allowed, space separated |
+| `args` | `""` | extra CLI arguments, e.g. `--conditional=warn --disable=WSL011` |
+| `format` | `github` | `github`, `stylish`, or `json` |
+
+Outputs: `errors`, `warnings`.
+
+## Rules
+
+Every error-level rule maps to one sentence Blizzard publishes. `wow-secret-lint --rules` prints the table with the source for each.
+
+| Rule | Severity | What it catches |
+| --- | --- | --- |
+| WSL001 | error | arithmetic on a secret value |
+| WSL002 | error | relational or equality comparison of a secret value |
+| WSL003 | error | calling a secret value as if it were a function |
+| WSL004 | error | length operator `#` on a secret value |
+| WSL005 | error | indexed access, indexed assignment, or a secret used as a table key |
+| WSL006 | error | secret passed to an API whose `SecretArguments` does not allow it |
+| WSL007 | error | boolean test on a secret whose documented return type is `bool` |
+| WSL008 | error | registering `COMBAT_LOG_EVENT` or `COMBAT_LOG_EVENT_UNFILTERED` |
+| 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 |
+
+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.
+
+### 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/`:
+
+- storing a secret in a variable, an upvalue, or as a value in a table
+- passing a secret to a Lua function
+- concatenating string or number secrets with `..`
+- calling `string.concat`, `string.format` or `string.join` with a secret
+- boolean tests on non-boolean secrets, e.g. `if UnitHealth(unit) then`
+
+That last one is why WSL007 checks the documented return type before it fires. `UnitInRange` returns a `bool` and is `SecretReturns = true`, so `if UnitInRange(u) then` is an error. `UnitHealth` returns a `number`, so `if hp then` is silent.
+
+### Guards
+
+Taint is cleared inside a branch guarded by `issecretvalue`, `canaccessvalue`, `issecrettable`, `canaccesstable` or `hasanysecretvalues`, by a frame's `HasSecretValues` / `HasSecretAspect`, and at any `scrubsecretvalues` or `secretwrap` boundary. `and`-chains, `else` branches and early returns all work:
+
+```lua
+if issecretvalue(hp) then return end
+local pct = hp / max * 100          -- silent, the early return guarded it
+```
+
+Almost every real addon wraps the raw guards. KkthnxUI ships `IsSecret`, BigWigs ships `self:IsSecret`. Any callee whose name starts with `is`/`has`/`hasany` + `secret`, or `canaccess`, is recognised as a guard automatically. For a wrapper with an unrelated name, pass it explicitly:
+
+```bash
+npx wow-secret-lint ./MyAddon --secret-guard=IsLocked --access-guard=CanRead
+```
+
+### Conditionally secret APIs
+
+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:
+
+```bash
+npx wow-secret-lint ./MyAddon --conditional=warn    # report as warnings
+npx wow-secret-lint ./MyAddon --conditional=error   # fail the build on them
+```
+
+It is precise about structure fields. Blizzard marks safe fields `NeverSecret = true`, so this reports line 13 and stays quiet on line 10:
+
+```lua
+local cooldown = C_Spell.GetSpellCooldown(spellID)
+if not cooldown.isEnabled then     -- isEnabled is NeverSecret, silent
+    return false
+end
+if cooldown.startTime ~= 0 then    -- startTime is not, reported
+    return false
+end
+```
+
+```
+$ npx wow-secret-lint --conditional=warn Talents.lua
+Talents.lua:13:5  warning  WSL002  comparison of a secret value: 'cooldown.startTime' derives from C_Spell.GetSpellCooldown() (conditionally secret: SecretWhenCooldownsRestricted)
+0 errors, 1 warning
+```
+
+That is [BtWLoadouts#67](https://github.com/Breeni/BtWLoadouts/issues/67), reduced to its shape.
+
+## Measured false positives
+
+Run against 12 real retail addons at default settings (BigWigs, LittleWigs, DBM, WeakAuras, Details, SpartanUI, KkthnxUI, oUF, Bartender4, Premade Groups Filter, BtWLoadouts, AdvancedInterfaceOptions): **2,209 Lua files, 118 errors, 0 warnings**, which is 0.053 findings per file. Six of the twelve addons are affected.
+
+Every one of the 118 was read against its source line by hand. **The false-positive count is 0.** They are overwhelmingly the same two shapes:
+
+```
+UnitHealth(uId) / UnitHealthMax(uId) * 100          WSL001
+frame:RegisterEvent("COMBAT_LOG_EVENT_UNFILTERED")  WSL008
+```
+
+Three of the twelve report nothing at all, and KkthnxUI is one of them: it already wraps its reads in `IsSecret`, and the guard heuristic sees that.
+
+With `--conditional=warn` the same corpus produces 118 errors and 2,166 warnings (1.03 per file). That number is why the tier is opt-in, and it is the honest cost of auditing the conditional surface.
+
+Blizzard's own `BlizzardInterfaceCode` (2,274 files) is also in the corpus as a parser stress test: **0 parse errors**. Its findings are not violations, because Blizzard's code runs untainted.
+
+## Configuration
+
+```
+--format=<stylish|json|github>  output format (default: stylish)
+--game=<retail|classic>         classic has no secret values and exits 0 immediately
+--conditional=<off|warn|error>  conditionally secret APIs (default: off)
+--secret-guard=<names>          extra is-secret wrapper functions, comma separated
+--access-guard=<names>          extra can-access wrapper functions, comma separated
+--disable=<ids>                 rule ids to silence, e.g. WSL010,WSL011
+--max-warnings=<n>              exit 1 when warnings exceed n
+--snapshot=<path>               use a different API snapshot
+--refresh                       rebuild the vendored API snapshot (the only networked command)
+--rules                         print the rule table with its sources
+```
+
+## Where the data comes from
+
+`data/api-snapshot.json` is built from Blizzard's generated API documentation, mirrored at [Gethe/wow-ui-source](https://github.com/Gethe/wow-ui-source) on the `live` branch. The current snapshot carries **10,098 documented functions and 752 structures**: 20 with `SecretReturns = true`, 310 conditionally secret, and per-field `NeverSecret` markers on 20 structures.
+
+It is parsed with `luaparse`, not regexed, so nested tables and multi-line entries cannot skew it. Rebuild it any time:
+
+```bash
+npx wow-secret-lint --refresh
+```
+
+A scheduled workflow in this repo does that weekly and opens a pull request when the docs move.
+
+## Limitations and non-goals
+
+- **No auto-fixing.** It tells you where; the fix is yours.
+- **No runtime component and no in-game addon.** This is a build-time linter.
+- **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(...)`.
+- **`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.
+
+## Tests
+
+```bash
+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:
+
+| Fixture | Issue |
+| --- | --- |
+| `kkthnxui-121-textheight-arithmetic` | [KkthnxUI#121](https://github.com/Kkthnx-Wow/KkthnxUI/issues/121) |
+| `kkthnxui-119-map-icon-arithmetic` | [KkthnxUI#119](https://github.com/Kkthnx-Wow/KkthnxUI/issues/119) |
+| `kkthnxui-118-secret-table-key` | [KkthnxUI#118](https://github.com/Kkthnx-Wow/KkthnxUI/issues/118) |
+| `aura-questor-68-textheight-arithmetic` | [aura-questor#68](https://github.com/lucascodev/aura-questor/issues/68) |
+| `betterfriendlist-133-missing-hassecretvalues-gate` | [BetterFriendlist#133](https://github.com/Hayato2846/BetterFriendlist/issues/133) |
+| `premade-groups-filter-399-searchresult-index` | [premade-groups-filter#399](https://github.com/0xbs/premade-groups-filter/issues/399) |
+| `btwloadouts-67-unguarded-cooldown-compare` | [BtWLoadouts#67](https://github.com/Breeni/BtWLoadouts/issues/67) |
+| `combat-log-event-registration` | [Patch 12.0.0 API changes](https://warcraft.wiki.gg/wiki/Patch_12.0.0/API_changes) |
+
+Each fixture reproduces the shape of the reported defect, not the exact runtime taint chain, and every one carries an `expected.json` pinning the rule id, line, severity and originating API. The header comment in each `input.lua` quotes the original trace.
+
+## Contributing
+
+A false positive is a bug and worth an issue. Include the Lua, the rule id, and what the API actually returns. A rule that fires on correct code is worse than a rule that misses.
+
+## License
+
+MIT

package/action/index.mjs

@@ -0,0 +1,141 @@
+// GitHub Action entrypoint. Runs the linter in-process against the checked-out workspace
+// and writes annotations plus a job summary. No install step, so src/ resolves luaparse
+// from vendor/ (see src/luaparse.mjs).
+
+import { appendFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+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';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function input(name, fallback = '') {
+  const key = `INPUT_${name.toUpperCase().replace(/ /g, '_')}`;
+  const v = process.env[key];
+  return v === undefined || v === '' ? fallback : v;
+}
+
+function splitArgs(raw) {
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(raw)) !== null) out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}
+
+async function setOutput(name, value) {
+  const file = process.env.GITHUB_OUTPUT;
+  if (!file) return;
+  await appendFile(file, `${name}=${value}\n`, 'utf8');
+}
+
+async function summary(markdown) {
+  const file = process.env.GITHUB_STEP_SUMMARY;
+  if (!file) return;
+  await appendFile(file, markdown, 'utf8');
+}
+
+function fail(message) {
+  process.stdout.write(`::error::${message.replace(/\r?\n/g, '%0A')}\n`);
+  process.exit(2);
+}
+
+const paths = splitArgs(input('path', '.'));
+const extra = splitArgs(input('args', ''));
+const fmt = input('format', 'github');
+
+if (!FORMATS.includes(fmt)) fail(`unknown format "${fmt}" (expected one of: ${FORMATS.join(', ')})`);
+
+const options = { conditional: 'off', disable: [], secretGuards: [], accessGuards: [], game: 'retail' };
+let maxWarnings = Infinity;
+
+for (let i = 0; i < extra.length; i++) {
+  const a = extra[i];
+  const eq = a.indexOf('=');
+  const key = eq === -1 ? a : a.slice(0, eq);
+  const val = () => (eq === -1 ? extra[++i] : a.slice(eq + 1));
+  switch (key) {
+    case '--conditional':
+      options.conditional = val();
+      break;
+    case '--game':
+      options.game = val();
+      break;
+    case '--disable':
+      options.disable.push(...val().split(',').map((s) => s.trim()).filter(Boolean));
+      break;
+    case '--secret-guard':
+      options.secretGuards.push(...val().split(',').map((s) => s.trim()).filter(Boolean));
+      break;
+    case '--access-guard':
+      options.accessGuards.push(...val().split(',').map((s) => s.trim()).filter(Boolean));
+      break;
+    case '--max-warnings':
+      maxWarnings = Number(val());
+      break;
+    case '--snapshot':
+      options.snapshotPath = val();
+      break;
+    default:
+      fail(`unknown value in "args": ${key}`);
+  }
+}
+
+if (!['off', 'warn', 'error'].includes(options.conditional)) {
+  fail(`unknown --conditional "${options.conditional}" (expected off, warn or error)`);
+}
+if (!['retail', 'classic'].includes(options.game)) {
+  fail(`unknown --game "${options.game}" (expected retail or classic)`);
+}
+for (const id of options.disable) {
+  if (!RULE_IDS.includes(id)) fail(`unknown rule id "${id}" in --disable`);
+}
+if (Number.isNaN(maxWarnings)) fail('--max-warnings needs a number');
+
+if (options.game === 'classic') {
+  process.stdout.write('::notice::classic has no secret values; nothing to check\n');
+  await setOutput('errors', 0);
+  await setOutput('warnings', 0);
+  process.exit(0);
+}
+
+options.snapshotPath ??= join(HERE, '..', 'data', 'api-snapshot.json');
+
+let merged;
+try {
+  merged = await lintPaths(paths, options);
+} catch (err) {
+  fail(err.message);
+}
+
+process.stdout.write(format(merged, fmt) + '\n');
+
+const { errors, warnings } = counts(merged);
+await setOutput('errors', errors);
+await setOutput('warnings', warnings);
+
+const rows = merged.findings
+  .slice(0, 50)
+  .map((f) => `| \`${f.file}:${f.line}:${f.column}\` | ${f.severity} | ${f.ruleId} | ${f.message.replace(/\|/g, '\\|')} |`)
+  .join('\n');
+
+await summary(
+  `## wow-secret-lint ${VERSION}\n\n` +
+    `${merged.filesScanned} Lua file(s) scanned against ${merged.snapshot.functionCount ?? 0} documented APIs ` +
+    `(${merged.snapshot.secretReturnCount ?? 0} with \`SecretReturns=true\`).\n\n` +
+    `**${errors} error(s), ${warnings} warning(s)**` +
+    (merged.parseErrors.length ? `, ${merged.parseErrors.length} parse error(s)` : '') +
+    '\n\n' +
+    (rows
+      ? `| Location | Severity | Rule | Message |\n| --- | --- | --- | --- |\n${rows}\n` +
+        (merged.findings.length > 50 ? `\n_${merged.findings.length - 50} more not shown._\n` : '')
+      : '_No findings._\n')
+);
+
+if (merged.parseErrors.length) process.exit(2);
+if (errors > 0) process.exit(1);
+if (warnings > maxWarnings) process.exit(1);
+process.exit(0);

package/action.yml

@@ -0,0 +1,32 @@
+name: 'wow-secret-lint'
+description: 'Find WoW retail addon Secret Value violations in Lua before they ship.'
+author: 'Booyaka101'
+branding:
+  icon: 'shield'
+  color: 'purple'
+
+inputs:
+  path:
+    description: 'Addon folder, .toc, or .lua file to lint. Accepts several, space separated.'
+    required: false
+    default: '.'
+  args:
+    description: 'Extra CLI arguments, e.g. "--conditional=warn --disable=WSL011".'
+    required: false
+    default: ''
+  format:
+    description: 'Output format: github (annotations), stylish, or json.'
+    required: false
+    default: 'github'
+
+outputs:
+  errors:
+    description: 'Number of error-severity findings.'
+    value: ${{ steps.lint.outputs.errors }}
+  warnings:
+    description: 'Number of warning-severity findings.'
+    value: ${{ steps.lint.outputs.warnings }}
+
+runs:
+  using: 'node20'
+  main: 'action/index.mjs'

package/bin/wow-secret-lint.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// wow-secret-lint CLI.
+//
+// Exit codes: 0 clean, 1 findings at error severity, 2 parse error or usage/runtime failure.
+
+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';
+
+const USAGE = `wow-secret-lint ${VERSION}
+Static analysis for World of Warcraft retail addons: finds Secret Value violations
+in Lua before they ship.
+
+Usage:
+  wow-secret-lint [options] <path>...
+
+  <path>  an addon folder (its .toc files decide the file list), a .toc, or a .lua file.
+
+Options:
+  --format=<stylish|json|github>  output format (default: stylish)
+  --game=<retail|classic>         classic has no secret values and exits 0 immediately
+  --conditional=<off|warn|error>  how to treat APIs Blizzard marks secret only under a
+                                  runtime restriction, e.g. SecretWhenCooldownsRestricted
+                                  or SecretInChatMessagingLockdown (default: off)
+  --secret-guard=<names>          extra is-secret wrapper functions, comma separated.
+                                  Names matching is*secret/has*secret are detected already.
+  --access-guard=<names>          extra can-access wrapper functions, comma separated
+  --disable=<ids>                 comma-separated rule ids to silence, e.g. WSL010,WSL011
+  --max-warnings=<n>              exit 1 when warnings exceed n (default: unlimited)
+  --snapshot=<path>               use a different API snapshot
+  --refresh                       rebuild the vendored API snapshot from the public mirror
+                                  (the only command that uses the network)
+  --rules                         print the rule table and exit
+  --version                       print the version and exit
+  -h, --help                      print this help and exit
+
+Rules: ${RULE_IDS.join(' ')}
+Docs:  https://github.com/Booyaka101/wow-secret-lint
+`;
+
+function fail(message, code = 2) {
+  process.stderr.write(`wow-secret-lint: ${message}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    format: 'stylish',
+    game: 'retail',
+    conditional: 'off',
+    disable: [],
+    secretGuards: [],
+    accessGuards: [],
+    maxWarnings: Infinity,
+    snapshot: undefined,
+    refresh: false,
+    rules: false,
+    help: false,
+    version: false,
+    paths: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') {
+      opts.paths.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg === '-h' || arg === '--help') opts.help = true;
+    else if (arg === '--version' || arg === '-v') opts.version = true;
+    else if (arg === '--refresh') opts.refresh = true;
+    else if (arg === '--rules') opts.rules = 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('--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));
+    else if (arg.startsWith('--disable')) opts.disable = value(arg, argv, () => i++).split(',').map((s) => s.trim()).filter(Boolean);
+    else if (arg.startsWith('--max-warnings')) opts.maxWarnings = Number(value(arg, argv, () => i++));
+    else if (arg.startsWith('--snapshot')) opts.snapshot = value(arg, argv, () => i++);
+    else if (arg.startsWith('-')) throw new Error(`unknown option "${arg}"`);
+    else opts.paths.push(arg);
+
+    function value(a, list, bump) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) return a.slice(eq + 1);
+      bump();
+      const next = list[i];
+      if (next === undefined) throw new Error(`option "${a}" needs a value`);
+      return next;
+    }
+  }
+  return opts;
+}
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`wow-secret-lint: ${err.message}\n\n${USAGE}`);
+    process.exit(2);
+  }
+
+  if (opts.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (opts.version) {
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+  if (opts.rules) {
+    for (const id of RULE_IDS) {
+      process.stdout.write(`${id}  ${RULES[id].severity.padEnd(7)}  ${RULES[id].summary}\n          ${RULES[id].source}\n`);
+    }
+    return 0;
+  }
+
+  if (opts.refresh) {
+    process.stderr.write('rebuilding API snapshot from Gethe/wow-ui-source@live ...\n');
+    let index;
+    try {
+      let last = 0;
+      index = await refreshSnapshot({
+        onProgress: ({ done, total }) => {
+          if (done - last >= 50 || done === total) {
+            last = done;
+            process.stderr.write(`  ${done}/${total} documentation files\n`);
+          }
+        },
+      });
+    } catch (err) {
+      fail(`--refresh failed: ${err.message}`);
+    }
+    const path = await writeSnapshot(index, opts.snapshot ?? SNAPSHOT_PATH);
+    process.stderr.write(
+      `wrote ${path}: ${index.functionCount} functions, ${index.secretReturnCount} with SecretReturns=true, ` +
+        `${index.conditionalCount} conditionally secret, ${index.structureCount} structures\n`
+    );
+    if (index.failures && index.failures.length) {
+      process.stderr.write(`  ${index.failures.length} file(s) could not be read: ${index.failures.map((f) => f.file).join(', ')}\n`);
+    }
+    return 0;
+  }
+
+  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 (!['warn', 'error', 'off'].includes(opts.conditional)) {
+    fail(`unknown --conditional "${opts.conditional}" (expected warn, error or off)`);
+  }
+  for (const id of opts.disable) {
+    if (!RULE_IDS.includes(id)) fail(`unknown rule id "${id}" in --disable (known: ${RULE_IDS.join(', ')})`);
+  }
+  if (Number.isNaN(opts.maxWarnings)) fail('--max-warnings needs a number');
+  if (!opts.paths.length) {
+    process.stderr.write(`wow-secret-lint: no path given\n\n${USAGE}`);
+    process.exit(2);
+  }
+
+  if (opts.game === 'classic') {
+    if (opts.format === 'stylish') process.stdout.write('classic has no secret values; nothing to check\n');
+    else if (opts.format === 'github') process.stdout.write('::notice::classic has no secret values; nothing to check\n');
+    else process.stdout.write(`${JSON.stringify({ version: VERSION, game: 'classic', findings: [], parseErrors: [], summary: { errors: 0, warnings: 0, parseErrors: 0 } }, null, 2)}\n`);
+    return 0;
+  }
+
+  let merged;
+  try {
+    merged = await lintPaths(opts.paths, {
+      game: opts.game,
+      conditional: opts.conditional,
+      disable: opts.disable,
+      secretGuards: opts.secretGuards,
+      accessGuards: opts.accessGuards,
+      snapshotPath: opts.snapshot,
+    });
+  } catch (err) {
+    fail(err.message);
+  }
+
+  process.stdout.write(format(merged, opts.format) + '\n');
+
+  const { errors, warnings } = counts(merged);
+  if (merged.parseErrors.length) return 2;
+  if (errors > 0) return 1;
+  if (warnings > opts.maxWarnings) return 1;
+  return 0;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(`wow-secret-lint: unexpected failure: ${err && err.stack ? err.stack : err}\n`);
+    process.exit(2);
+  });