roblox-guard 0.4.0 → 0.5.0

package/AGENTS.md

@@ -0,0 +1,77 @@
+# Roblox and Luau standards
+
+Scope: every `.luau` and `.lua` file in a Roblox project. These rules govern how each script is
+written, not how the project is structured, so they hold under any framework or folder layout.
+
+They are active instruction, not background reading. Carry them forward verbatim into any
+summary, handoff, or task note. Never reconstruct them from memory: a half-remembered layout
+rule looks deliberate and is worse than none.
+
+```text
+ROBLOX LUAU SKILL - INVARIANT CARD
+1  Three sections, this order:
+   -- // VARIABLES // --   Services > Modules > Objects > Configuration > State Management
+   -- // FUNCTIONS // --   definitions only (ModuleScript: Private before Public)
+   -- // INITIALIZATION // --   everything that runs
+   Omit a section that would be empty. Never write a placeholder header.
+2  Documentation Comments (Luau Comments) - default style, adapts to the project.
+   Default block: --[[ ]] above the function, desc > @param > @return.
+   Moonwave --[=[ ]=] or --- is equally correct when that is the project's style.
+   - Desc <= 3 lines and <= 250 chars, contract-level, states PURPOSE.
+   - Desc never names what the body does to get there: no APIs, algorithms,
+     collaborators, data structures, or code paths.
+   - Desc carries NO volatile content: no numbers, thresholds, tunable names,
+     feature names, or anything that needs editing when the body is retuned.
+   - Tags use Moonwave syntax: @param <name> <type> -- <description>
+     and @return <type> -- <description>. Only when they add what the
+     signature cannot show.
+   - English preferred. No em dashes or double-hyphen dashes as punctuation
+     (the -- in a tag is a separator, not punctuation). No emoji.
+   - IN-BODY COMMENTS: banned in code you write. Make names and structure say
+     it; put the why in the block above. Never delete an existing one;
+     propose removal once, Advisory only.
+   - Self-documenting code outranks commentary everywhere.
+   - Existing project comment style wins. Recommend this style when the user
+     asks to restyle; never impose it.
+3  Server is authoritative. Validate every remote arg: type, range, ownership, rate.
+4  Clean up everything created. Every connection has an owner and a teardown path.
+5  No avoidable per-frame garbage. Never poll what has a signal.
+6  UpdateAsync + backoff. Save on PlayerRemoving. Flush on BindToClose.
+7  Re-validate after every yield: player gone? instance dead? session changed?
+8  Never add --!strict unbidden. Never make a [Beta] feature the production default.
+9  Reuse before writing: project, then stdlib, then engine API. No wrapper or
+   abstraction without a caller. But brevity has two hard limits:
+   - It NEVER reduces what was asked for. Short because it does less = failed.
+   - It NEVER costs readability. One statement per line, descriptive names,
+     blank lines kept. Less code means less WORK, not less whitespace.
+10 No deprecated APIs: wait, spawn, delay, tick, lowercase :connect,
+   Humanoid:LoadAnimation, SetPrimaryPartCFrame, Body* movers.
+11 Engine facts are cited, not remembered. Confirm a newer API against the
+   version dump or an in-Studio probe before relying on it.
+12 User authority outranks these rules. Recommend; never refactor unasked.
+```
+
+## Full standards
+
+This card is the part that must survive a summary. The complete standards, with the reference
+files behind each rule, live in this repository:
+
+| Path | Covers |
+|---|---|
+| `skills/best-practices/SKILL.md` | Writing and refactoring Luau |
+| `skills/code-review/SKILL.md` | Reviewing, auditing, and scoring existing code |
+| `skills/studio-ops/SKILL.md` | Studio MCP, sync toolchains, verifying in a running session |
+
+Read the one whose task matches. Each reference file is self-contained; read one, not the set.
+
+## The checks run outside you
+
+`scripts/roblox-guard.mjs` reports deprecated APIs and out-of-order section headers
+deterministically, with no model involved. Run it on the files you touched before you report
+work as done:
+
+```
+node scripts/roblox-guard.mjs --check <files>
+```
+
+It exits 1 when a file has findings, and each finding names the line and the replacement.

package/LICENSE

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

@@ -9,6 +9,7 @@ Professional Roblox and Luau standards for AI agents, and a checker that runs wi
 [![CI](https://github.com/andrian-syh/roblox-optimum/actions/workflows/ci.yml/badge.svg)](https://github.com/andrian-syh/roblox-optimum/actions/workflows/ci.yml)
 [![version](https://img.shields.io/github/package-json/v/andrian-syh/roblox-optimum?label=version&color=blue)](CHANGELOG.md)
 [![license](https://img.shields.io/github/license/andrian-syh/roblox-optimum?color=green)](LICENSE)
+[![npm](https://img.shields.io/npm/v/roblox-guard?label=npm&color=CB3837)](https://www.npmjs.com/package/roblox-guard)
 [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
 [![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
 
@@ -25,8 +26,8 @@ Claude Code, and as a project instruction file everywhere else. [AGENTS.md](AGEN
 ready to copy, along with a matching file for Cursor, Windsurf, Cline, Kiro, Qoder, Copilot,
 Qwen Code, and Antigravity.
 
-**The checker** is [`scripts/roblox-guard.mjs`](scripts/roblox-guard.mjs), one Node file with no
-dependencies. It reads Luau and reports the same findings whoever wrote the file, so it works as
+**The checker** is [`roblox-guard`](https://www.npmjs.com/package/roblox-guard) on npm, one Node
+file with no dependencies. It reads Luau and reports the same findings whoever wrote the file, so it works as
 an agent hook, a commit hook, or a CI step. It never asks a model anything, which is why it still
 holds after a long session has been summarized and the rules have fallen out of context.
 
@@ -54,9 +55,15 @@ Qwen Code:
 qwen extensions install https://github.com/andrian-syh/roblox-optimum
 ```
 
-Cursor, Antigravity, and Kiro install it as a plugin from this repository. For those, plus
-OpenCode, Copilot, or a plain commit hook, see **[INSTALL.md](INSTALL.md)**, which also states
-plainly what each setup can and cannot do.
+Cursor, Antigravity, Kiro, and Copilot CLI install it as a plugin from this repository. For those,
+plus OpenCode or a plain commit hook, see **[INSTALL.md](INSTALL.md)**, which also states plainly
+what each setup can and cannot do.
+
+The checker on its own needs no repository at all:
+
+```
+npx roblox-guard --check src/**/*.luau
+```
 
 ## Skills
 
@@ -113,6 +120,16 @@ or synced, belong to a project rather than to a person, and are resolved per ses
 Deprecated APIs and out-of-order section headers. Where the agent can receive them, findings go
 straight back to it and it fixes its own output before you see it.
 
+```
+$ npx roblox-guard --check CoinService.luau
+Roblox standards check failed for CoinService.luau:
+  - Line 5: :connect() is deprecated. Use :Connect().
+  - Line 6: wait() is deprecated. Use task.wait().
+  - Line 8: Humanoid:LoadAnimation() is deprecated. Use Animator:LoadAnimation().
+```
+
+Exit 1, so a commit hook or a build step stops on it.
+
 The check is deliberately conservative, because a wrong complaint gets a guard switched off:
 
 - Comments and string literals are excluded, so a rule quoted in prose is never reported as a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roblox-guard",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Deterministic Roblox and Luau standards checks: deprecated APIs and out-of-order section headers, as an agent hook, a commit hook, or a CI step.",
   "keywords": [
     "roblox",
@@ -17,7 +17,8 @@
     "roblox-guard": "scripts/roblox-guard.mjs"
   },
   "files": [
-    "scripts/roblox-guard.mjs"
+    "scripts/roblox-guard.mjs",
+    "AGENTS.md"
   ],
   "scripts": {
     "test": "node scripts/roblox-guard.mjs --selftest"

package/scripts/roblox-guard.mjs

@@ -188,15 +188,21 @@ export function inspect(source) {
   }
 
   const lines = code.split("\n");
+  const deprecated = [];
+
   for (const [pattern, name, replacement] of DEPRECATED) {
     for (let k = 0; k < lines.length; k++) {
       if (pattern.test(lines[k])) {
-        problems.push(`Line ${k + 1}: ${name} is deprecated. Use ${replacement}.`);
+        deprecated.push({ line: k + 1, text: `Line ${k + 1}: ${name} is deprecated. Use ${replacement}.` });
         break;
       }
     }
   }
 
+  // Report in reading order. Grouping by pattern is how they are found, not how they are read.
+  deprecated.sort((a, b) => a.line - b.line);
+  problems.push(...deprecated.map((d) => d.text));
+
   return problems;
 }
 
@@ -399,6 +405,15 @@ Players.PlayerAdded:Connect(greet)
     inspect(good.replace("task.wait(1)", "wait(1)")).some((p) => p.includes("wait()")),
     "bare wait() is caught",
   );
+  ok(
+    (() => {
+      const lines = inspect(`-- // VARIABLES // --\nlocal a = 1\n-- // INITIALIZATION // --\nspawn(function()\n\twait(1)\nend)\nx:connect(f)`)
+        .map((p) => Number(p.match(/^Line (\d+)/)?.[1]))
+        .filter(Number.isFinite);
+      return lines.length === 3 && lines.every((n, k) => k === 0 || n >= lines[k - 1]);
+    })(),
+    "findings are reported in line order, not pattern order",
+  );
   ok(
     !inspect(good).some((p) => p.includes("wait()")),
     "task.wait() is not mistaken for wait()",