bar-fmt: lua codemod, workspace integration, LLM type-triage (rollup)

.claude/skills/type-fixes-preserve-behavior/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: type-fixes-preserve-behavior
+description: A type-error fix may change types and names — never behavior. Use when clearing emmylua_check errors in the Beyond-All-Reason tree, or on any pass that renames locals, adopts a namespace (Spring.X -> BAR.X), or edits a file to satisfy the analyzer. It encodes the gui_chat.lua regression that shipped a widget that would not load.
+---
+
+# Type fixes preserve behavior
+
+`emmylua_check` reports a *type* problem. The fix is a type annotation, a declaration, or a name — never a restructured function, never a dropped field, never an inlined recomputation. A green analyzer on a widget that no longer loads is worse than the error it replaced.
+
+## The rule
+
+**Every edit is reversible into "same program, better typed."** If you cannot state the change as a rename, an annotation, or a declaration, you are no longer fixing a type error.
+
+## Renames are total or they are not done
+
+Renaming a local means renaming *every* reader in the file, in one pass. Count the references before and after — they must match.
+
+```lua
+-- state table renamed I18N -> i18nStrings
+local i18nStrings = state.i18nStrings   -- renamed
+...
+local modeText = I18N.everyone          -- NOT renamed: now a nil global
+```
+
+A partial rename is silent at load and crashes on the first draw. `grep -c` the old name after the edit; the answer is 0.
+
+## A namespace prefix is not noise
+
+`Spring.I18N(...)` -> `BAR.I18N(...)` is the migration. `BAR.I18N(...)` -> `I18N(...)` is a bug, unless the file declares `local I18N = BAR.I18N` — and if it does, that declaration must be in the same edit.
+
+Bare `I18N(` reads as a local alias. Grep the file for the `local ... = BAR.` line before assuming one exists.
+
+## Never drop a table field
+
+A key removed from a constructor is a runtime nil at every read site. Two keys (`channelScopeAll`, `label`) went missing from a table while its readers stayed — both would have returned nil forever.
+
+Diff the constructor key-set before and after. It only grows.
+
+## Never introduce shadowing recomputation
+
+Do not re-declare inside a closure what the enclosing function already computed. Fifteen such lines were inserted into a `glCreateList(function() ... end)`, recomputing `isCmd` *without* the `isLabel` branch the outer scope had — a behavior regression the analyzer is blind to.
+
+If a closure needs a value, it already has it as an upvalue.
+
+## Not every .lua file is Lua
+
+`mapgenerator/mapinfo_template.lua` is a `${PLACEHOLDER}` template. A bare
+`${START_POSITIONS}` inside a table is a parse error, and commenting it out
+silences the analyzer while breaking every generated map — the substituted
+block lands behind a `--`.
+
+A file the analyzer cannot parse for a structural reason belongs in
+`.emmyrc.json` `workspace.ignoreDir`, not in your edit set. Ask what the file
+*is* before treating a diagnostic on it as a defect.
+
+## Repair to the intent, not to whatever is in scope
+
+`stompableDefs[udid] = v` — `v` leaked from a previous loop and was nil, so the
+table was always empty. `ud` is in scope and makes the error go away; `true` is
+what the code meant, because the only read is `if stompableDefs[unitDefID]`.
+
+When a table is used as a set, the value is `true`. Look at the read sites
+before choosing the write.
+
+## Verify before committing
+
+- `luajit -bl <file> >/dev/null` — syntax.
+- `git diff <pre-pass-commit> -- <file>` — every changed line is a rename, an annotation, or a declaration. Line count does not grow.
+- Load the game and read `infolog.txt` for `Failed to load:`. The analyzer cannot see a nil global that is only called at load.

.emmyrc.json

@@ -0,0 +1,7 @@
+{
+	"workspace": {
+		"ignoreDir": [
+			".devtools"
+		]
+	}
+}

.gitignore

@@ -18,12 +18,15 @@ bar_debug_launcher
 repos.local.conf
 .env
 
+# Build artifacts
+target/
+bar-mission-kit/vscode/server/bar-mission-kit
+
 # Runtime / editor state
 tasks/
 .devtools/
 .backups/
 *.log
-bar-lua-codemod/target/
 .claude/settings.local.json
 .claude/projects/
 .claude/todos/

README.md

@@ -1,8 +1,6 @@
 # BAR Devtools
 
-Local development environment for [Beyond All Reason](https://www.beyondallreason.info/) -- spins up **Teiserver** (lobby server), **PostgreSQL**, **SPADS** (autohost), and **bar-lobby** (game client) with a single command.
-
-Everything server-side runs in Docker. The game client runs natively.
+Shared development environment for [Beyond All Reason](https://www.beyondallreason.info/) — game code (Lua), engine (C++), lobby server (Elixir), and autohost (Perl) all from one repo.
 
 ## Quickstart (Linux)
 
@@ -164,6 +162,14 @@ just bar::lx-shell      # interactive lx shell for package work
                         #   (`lx add <pkg>`, `lx sync`, `lx install`, etc.)
 ```
 
+> **⚠️ Merge conflicts with master?** The project ships deterministic code transforms (formatting, API renames, Spring split) that can be replayed onto any branch. Transform your branch first, then merge:
+> ```bash
+> just bar::migrate::stylua-cleanup      # transform your branch first
+> git commit -am "apply code transforms"  # squashed away when PR merges
+> git merge origin/master                 # conflicts are now real conflicts only
+> ```
+> This is idempotent — safe to run multiple times. Includes `bar::fmt`, so no need to run it separately.
+
 ### Teiserver development
 
 Tests run in a separate container with `MIX_ENV=test`, so they work whether or not `services::up` is running. The test database is independent from the dev database.
@@ -243,6 +249,7 @@ just services::down             # stop everything
 just services::logs teiserver   # tail logs
 just services::shell teiserver  # open bash inside the running container
 ```
+The SPADS bot account (`spadsbot` / `password`) is created automatically during Teiserver init.
 
 ## Requirements
 
@@ -306,32 +313,15 @@ This runs a read-only check of your system dependencies, environment, ports, rep
 
 **Port 5432/5433 conflict with host PostgreSQL:**
 Either stop your local PostgreSQL (`sudo systemctl stop postgresql`) or change the port:
+**Port conflict with host PostgreSQL:**
 ```bash
 BAR_POSTGRES_PORT=5434 just services::up
 ```
 
-**Teiserver takes forever on first run:**
-The initial database seeding includes generating fake data. Follow progress with:
-```bash
-just services::logs teiserver
-```
+**Teiserver takes forever on first run:** Initial DB seeding generates fake data. Follow progress with `just services::logs teiserver`.
 
-**SPADS fails with "No Spring map/mod found":**
-Game data download may have failed. Check logs and retry:
-```bash
-just services::logs spads
-just services::down
-just services::up spads
-```
+**SPADS "No Spring map/mod found":** Game data download may have failed. `just services::down && just services::up spads`.
 
-**Docker permission denied:**
-```bash
-sudo usermod -aG docker $USER
-# Then log out and back in
-```
+**Docker permission denied:** `sudo usermod -aG docker $USER` then log out and back in.
 
-**Nuclear option -- start completely fresh:**
-```bash
-just services::reset
-just services::up
-```
+**Nuclear option:** `just services::reset && just services::up`