From 7b9cb0e14b1c038ad5b802969904a9cea9944e83 Mon Sep 17 00:00:00 2001 From: Rikard Blixt Date: Mon, 17 Aug 2026 13:16:01 +0200 Subject: [PATCH 1/3] chore: Add CLAUDE.md pointing tooling at the devcontainer Claude Code sessions default to whatever is on the host, which for this repository is usually a partial toolchain: lua may be a different version, and busted or luacheck may be missing entirely, so results do not say much about what CI will do. Points it at the devcontainer instead, and tells it to stop rather than fall back to the host when docker is unavailable. Also records the things that are easy to get wrong from the outside: that lint:js edits files, that snapshots are CI's to update, and that deploy.py writes to the live wiki without LUA_DEV_ENV_NAME. --- CLAUDE.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000000..8b52bc627dc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,50 @@ +# Lua-Modules + +## Running repository commands + +The toolchain lives in the devcontainer, not on the host: Lua 5.1, busted, +luacheck, lua-language-server, ruff, and the Playwright browsers the visual +snapshot tests need. Run repository commands there so results match CI. + +When the shell is already inside the container, which you can tell from the +workspace being under `/workspaces/`, run commands directly: + +``` +npm run lua-test +``` + +From the host, go through the devcontainer CLI, starting the container first if +it is not already up: + +``` +npx --yes @devcontainers/cli up --workspace-folder . +npx --yes @devcontainers/cli exec --workspace-folder . npm run lua-test +``` + +This needs Docker running. If Docker is not available, say so rather than +falling back to whatever is installed on the host — a host may have a different +Lua version, or no busted at all, and a result from it does not tell you what CI +will do. + +## Commands + +- `npm run lua-test` — busted suite, builds the CSS first +- `luacheck lua --config lua/.luacheckrc` — Lua lint +- `npm run lint:scss` — SCSS lint +- `npm run lint:js` — JS lint, note that it runs `eslint --fix` and edits files +- `ruff check scripts/` and `ruff format --check scripts/` — Python +- `npm run build` — CSS and JS bundles + +## Visual snapshots + +Do not update snapshots locally. CI regenerates them and commits them back to +the branch, and reviewing that diff is part of reviewing the pull request. +Rendering is not identical across CPU architectures, so a local update can +produce changed files that are not real changes. + +## Deploying to the wiki + +`scripts/deploy.py` writes to liquipedia.net. Set `LUA_DEV_ENV_NAME` so it +targets sandbox pages, and keep `DRY_RUN=1` unless the intent is a live write. +With neither set, running it with no arguments resyncs every module to the live +wiki. From 2ede9bbc27c9506606100badaa00424cde847baf Mon Sep 17 00:00:00 2001 From: Rikard Blixt Date: Mon, 17 Aug 2026 13:18:15 +0200 Subject: [PATCH 2/3] chore: Allow falling back to the host toolchain Refusing to run anything without docker is stricter than it needs to be, since a complete host toolchain gives a usable answer. Allows the fallback, on the conditions that the tool is confirmed present rather than assumed, and that the result says which environment produced it, so a host result is not mistaken for a container one. --- CLAUDE.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8b52bc627dc..8daaf9f9e26 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,10 +21,16 @@ npx --yes @devcontainers/cli up --workspace-folder . npx --yes @devcontainers/cli exec --workspace-folder . npm run lua-test ``` -This needs Docker running. If Docker is not available, say so rather than -falling back to whatever is installed on the host — a host may have a different -Lua version, or no busted at all, and a result from it does not tell you what CI -will do. +If Docker is not running, or the devcontainer is not set up, fall back to the +host toolchain. Two conditions on that: + +- Check the tool is actually installed first, `command -v busted`, rather than + discovering it from a confusing error. If it is missing, say so instead of + skipping the check or calling it passed. Installing the Lua ones is + `luarocks install --lua-version=5.1 busted` and the same for `luacheck`. +- Say which environment a result came from. A host may have a different Lua + version or an older ruff, so a host result is weaker evidence about CI than a + container one, and whoever reads the result should know which they got. ## Commands From 17f3de3cd059e100b58be60151a68b8cf2d007f6 Mon Sep 17 00:00:00 2001 From: Rikard Blixt Date: Mon, 17 Aug 2026 13:20:02 +0200 Subject: [PATCH 3/3] chore: Treat native and devcontainer setups as equals The previous wording made the devcontainer the canonical setup and the host a fallback, which is not how this repository works. Contributors install the toolchain natively too, which is straightforward on linux, where the devcontainer mostly earns its keep on macos and its deprecated lua@5.1 formula. Asks it to check what the machine has instead, run there, and keep the part that matters, that a result names the setup it came from. --- CLAUDE.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8daaf9f9e26..bb0a21f21d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,35 +2,39 @@ ## Running repository commands -The toolchain lives in the devcontainer, not on the host: Lua 5.1, busted, -luacheck, lua-language-server, ruff, and the Playwright browsers the visual -snapshot tests need. Run repository commands there so results match CI. +The toolchain can be installed natively or come from the devcontainer, and both +are supported — see Setup in the README. Use whichever the machine already has +rather than assuming one; a native setup is common on Linux, while the +devcontainer saves a fight with Lua 5.1 on macOS. -When the shell is already inside the container, which you can tell from the -workspace being under `/workspaces/`, run commands directly: +Check before running rather than guessing: `command -v busted luacheck ruff`, +and `lua -v`, which needs to report 5.1. Anything newer is unsupported here, so +its results do not mean much. + +With a native toolchain, or from a shell already inside the devcontainer, which +you can tell from the workspace being under `/workspaces/`, run commands +directly: ``` npm run lua-test ``` -From the host, go through the devcontainer CLI, starting the container first if -it is not already up: +From the host with only the devcontainer set up, go through its CLI, starting +the container first if it is not already up: ``` npx --yes @devcontainers/cli up --workspace-folder . npx --yes @devcontainers/cli exec --workspace-folder . npm run lua-test ``` -If Docker is not running, or the devcontainer is not set up, fall back to the -host toolchain. Two conditions on that: +If neither is available, say so instead of skipping a check or calling it +passed. Installing the Lua tools natively is `luarocks install --lua-version=5.1 +busted`, and the same for `luacheck`; the devcontainer route needs Docker +running. -- Check the tool is actually installed first, `command -v busted`, rather than - discovering it from a confusing error. If it is missing, say so instead of - skipping the check or calling it passed. Installing the Lua ones is - `luarocks install --lua-version=5.1 busted` and the same for `luacheck`. -- Say which environment a result came from. A host may have a different Lua - version or an older ruff, so a host result is weaker evidence about CI than a - container one, and whoever reads the result should know which they got. +Say which of the two produced a result when it is not obvious. A native setup +can differ from CI in Lua patch version or ruff version, and whoever reads the +result should know which they got. ## Commands