@codyswann/lisa 2.178.5 → 2.179.0

package/dist/configs/eslint/phaser.d.ts

@@ -1,14 +1,8 @@
-/**
- * ESLint 9 Flat Config - Phaser Stack
- *
- * Extends Lisa's TypeScript config with Phaser 4 enforcement: bans Phaser 3
- * rendering idioms that were removed in v4 and non-deterministic randomness
- * in game code.
- * @module configs/eslint/phaser
- */
 import type { Linter } from "eslint";
 import { defaultIgnores, defaultThresholds } from "./typescript.js";
 export { defaultIgnores, defaultThresholds };
+declare const phaserPlugin: any;
+export { phaserPlugin };
 /**
  * Default ignore patterns for Phaser projects.
  */

package/dist/configs/eslint/phaser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phaser.d.ts","sourceRoot":"","sources":["../../../src/configs/eslint/phaser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EACL,cAAc,EACd,iBAAiB,EAElB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AA8DF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAC9B,eAAe,EACf,cAAqC,EACrC,UAA8B,GAC/B,EAAE;IACD,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,iBAAiB,CAAC;CACvC,GAAG,MAAM,CAAC,MAAM,EAAE,CAoBlB"}
+{"version":3,"file":"phaser.d.ts","sourceRoot":"","sources":["../../../src/configs/eslint/phaser.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EACL,cAAc,EACd,iBAAiB,EAElB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;AAM7C,QAAA,MAAM,YAAY,KAIjB,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AA4MF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAC9B,eAAe,EACf,cAAqC,EACrC,UAA8B,GAC/B,EAAE;IACD,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,iBAAiB,CAAC;CACvC,GAAG,MAAM,CAAC,MAAM,EAAE,CAKlB"}

package/dist/configs/eslint/phaser.js

@@ -1,5 +1,26 @@
+/**
+ * ESLint 9 Flat Config - Phaser Stack
+ *
+ * Extends Lisa's TypeScript config with Phaser 4 enforcement:
+ * - bans Phaser 3 rendering/API idioms removed in v4,
+ * - enforces determinism (no Math.random/Date.now/performance.now in game code),
+ * - enforces the architecture boundary (src/logic must be Phaser-free),
+ * - bans reusing game.events, shipping physics debug:true, and raw localStorage,
+ * - registers eslint-plugin-phaser for the per-frame/lifecycle rules that cannot
+ *   be expressed as static selectors (no-create-in-update,
+ *   no-allocation-in-update, require-shutdown-cleanup).
+ * @module configs/eslint/phaser
+ */
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
 import { defaultIgnores, defaultThresholds, getTypescriptConfig, } from "./typescript.js";
 export { defaultIgnores, defaultThresholds };
+// Custom plugin — loaded via relative path so it resolves from the Lisa package
+// itself (eslint-plugin-* dirs are in the published files array) rather than the
+// registry. Same pattern as the code-organization plugin in typescript.ts.
+const require = createRequire(import.meta.url);
+const phaserPlugin = require(fileURLToPath(new URL("../../../eslint-plugin-phaser/index.js", import.meta.url)));
+export { phaserPlugin };
 /**
  * Default ignore patterns for Phaser projects.
  */
@@ -50,10 +71,130 @@ const PHASER_3_IDIOM_BANS = [
         selector: "NewExpression[callee.object.object.name='Phaser'][callee.object.property.name='Display'][callee.property.name='BitmapMask']",
         message: "Phaser 4 removed BitmapMask. Use the Mask filter.",
     },
+    {
+        selector: "MemberExpression[property.name='Mesh'][object.property.name='GameObjects']",
+        message: "Phaser 4 removed Mesh. Use Sprites/Containers, or SpriteGPULayer for mass rendering.",
+    },
+    {
+        selector: "MemberExpression[property.name='Plane'][object.property.name='GameObjects']",
+        message: "Phaser 4 removed Plane. Use Sprites/Containers.",
+    },
+    {
+        selector: "MemberExpression[property.name='Camera3D']",
+        message: "Phaser 4 removed Camera3D. There is no 3D camera in v4.",
+    },
+    {
+        selector: "MemberExpression[property.name='Layer3D']",
+        message: "Phaser 4 removed Layer3D. There is no 3D layer in v4.",
+    },
+];
+/**
+ * Determinism and architecture bans for Phaser game code (src/**, non-test).
+ */
+const PHASER_GAME_BANS = [
     {
         selector: "CallExpression[callee.object.name='Math'][callee.property.name='random']",
         message: "Game code must be deterministic. Use the seeded Phaser.Math.RND (RandomDataGenerator) instead of Math.random().",
     },
+    {
+        selector: "CallExpression[callee.object.name='Date'][callee.property.name='now']",
+        message: "Game code must be deterministic. Use the scene clock (update(time, delta)) or seeded RNG, not Date.now().",
+    },
+    {
+        selector: "CallExpression[callee.object.name='performance'][callee.property.name='now']",
+        message: "Game code must be deterministic. Use the scene clock (update(time, delta)), not performance.now().",
+    },
+    {
+        selector: "MemberExpression[property.name='events'][object.property.name='game'][object.object.type='ThisExpression']",
+        message: "Do not reuse this.game.events as an app bus — it collides with Phaser internals. Create a dedicated EventsCenter (new Phaser.Events.EventEmitter()) in src/services. See the phaser-services skill.",
+    },
+    {
+        selector: ":matches(Property[key.name='physics'], Property[key.name='arcade'], Property[key.name='matter']) Property[key.name='debug'][value.value=true]",
+        message: "Never ship physics debug:true. Gate it behind an env flag (e.g. import.meta.env.DEV).",
+    },
+];
+const LOGIC_IMPORT_MESSAGE = "src/logic must be Phaser-free (pure, testable game logic). Keep all Phaser usage in scenes/objects/services and pass plain data into logic.";
+/**
+ * Phaser-specific ESLint overrides layered on top of the TypeScript config.
+ * Hoisted to module scope so the factory stays small; they close over the
+ * module-level bans, plugin, and boundary message (no per-call parameters).
+ */
+const PHASER_OVERRIDES = [
+    // Game code: idiom bans, determinism, localStorage discipline, and the
+    // stateful per-frame/lifecycle rules. Test files are excluded.
+    {
+        files: ["src/**/*.ts"],
+        ignores: ["src/**/*.test.ts", "src/**/*.spec.ts"],
+        plugins: { phaser: phaserPlugin },
+        rules: {
+            "no-restricted-syntax": [
+                "error",
+                ...PHASER_3_IDIOM_BANS,
+                ...PHASER_GAME_BANS,
+            ],
+            "no-restricted-globals": [
+                "error",
+                {
+                    name: "localStorage",
+                    message: "Use the typed SaveService (src/services), not raw localStorage — it centralizes schema versioning and migration. See the phaser-services skill.",
+                },
+                {
+                    name: "sessionStorage",
+                    message: "Use a typed service (src/services), not raw sessionStorage.",
+                },
+            ],
+            "no-restricted-properties": [
+                "error",
+                {
+                    object: "window",
+                    property: "localStorage",
+                    message: "Use the typed SaveService (src/services), not window.localStorage.",
+                },
+                {
+                    object: "window",
+                    property: "sessionStorage",
+                    message: "Use a typed service (src/services), not window.sessionStorage.",
+                },
+            ],
+            "phaser/no-create-in-update": "error",
+            "phaser/no-allocation-in-update": "error",
+            "phaser/require-shutdown-cleanup": "error",
+        },
+    },
+    // The architecture boundary: pure logic may not import Phaser.
+    {
+        files: ["src/logic/**/*.ts"],
+        ignores: ["src/logic/**/*.test.ts", "src/logic/**/*.spec.ts"],
+        rules: {
+            "no-restricted-imports": [
+                "error",
+                {
+                    paths: [{ name: "phaser", message: LOGIC_IMPORT_MESSAGE }],
+                    patterns: [
+                        { group: ["phaser", "phaser/*"], message: LOGIC_IMPORT_MESSAGE },
+                    ],
+                },
+            ],
+        },
+    },
+    // Services own the persistence boundary, so they may touch storage directly.
+    {
+        files: ["src/services/**/*.ts"],
+        rules: {
+            "no-restricted-globals": "off",
+            "no-restricted-properties": "off",
+        },
+    },
+    // Tests can do anything (mock removed APIs, allocate freely, etc.).
+    {
+        files: ["tests/**/*.ts", "src/**/*.test.ts", "src/**/*.spec.ts"],
+        rules: {
+            "no-restricted-syntax": "off",
+            "no-restricted-imports": "off",
+            "no-restricted-globals": "off",
+            "no-restricted-properties": "off",
+        },
+    },
 ];
 /**
  * Creates the Phaser ESLint configuration.
@@ -65,23 +206,8 @@ const PHASER_3_IDIOM_BANS = [
  */
 export function getPhaserConfig({ tsconfigRootDir, ignorePatterns = defaultPhaserIgnores, thresholds = defaultThresholds, }) {
     return [
-        ...getTypescriptConfig({
-            tsconfigRootDir,
-            ignorePatterns,
-            thresholds,
-        }),
-        {
-            files: ["src/**/*.ts"],
-            rules: {
-                "no-restricted-syntax": ["error", ...PHASER_3_IDIOM_BANS],
-            },
-        },
-        {
-            files: ["tests/**/*.ts", "src/**/*.test.ts"],
-            rules: {
-                "no-restricted-syntax": "off",
-            },
-        },
+        ...getTypescriptConfig({ tsconfigRootDir, ignorePatterns, thresholds }),
+        ...PHASER_OVERRIDES,
     ];
 }
 //# sourceMappingURL=phaser.js.map

package/dist/configs/eslint/phaser.js.map

@@ -1 +1 @@
-{"version":3,"file":"phaser.js","sourceRoot":"","sources":["../../../src/configs/eslint/phaser.ts"],"names":[],"mappings":"AASA,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,GAAG,cAAc;IACjB,mBAAmB;IACnB,kBAAkB;IAClB,UAAU;CACX,CAAC;AAEF;;;GAGG;AACH,MAAM,mBAAmB,GAGnB;IACJ;QACE,QAAQ,EAAE,oDAAoD;QAC9D,OAAO,EACL,+HAA+H;KAClI;IACD;QACE,QAAQ,EAAE,wDAAwD;QAClE,OAAO,EACL,uGAAuG;KAC1G;IACD;QACE,QAAQ,EAAE,sDAAsD;QAChE,OAAO,EACL,2EAA2E;KAC9E;IACD;QACE,QAAQ,EAAE,oDAAoD;QAC9D,OAAO,EACL,wFAAwF;KAC3F;IACD;QACE,QAAQ,EAAE,yCAAyC;QACnD,OAAO,EACL,wGAAwG;KAC3G;IACD;QACE,QAAQ,EAAE,0CAA0C;QACpD,OAAO,EACL,yGAAyG;KAC5G;IACD;QACE,QAAQ,EACN,mGAAmG;QACrG,OAAO,EAAE,uDAAuD;KACjE;IACD;QACE,QAAQ,EAAE,gEAAgE;QAC1E,OAAO,EAAE,uDAAuD;KACjE;IACD;QACE,QAAQ,EACN,6HAA6H;QAC/H,OAAO,EAAE,mDAAmD;KAC7D;IACD;QACE,QAAQ,EACN,0EAA0E;QAC5E,OAAO,EACL,iHAAiH;KACpH;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,eAAe,EACf,cAAc,GAAG,oBAAoB,EACrC,UAAU,GAAG,iBAAiB,GAK/B;IACC,OAAO;QACL,GAAG,mBAAmB,CAAC;YACrB,eAAe;YACf,cAAc;YACd,UAAU;SACX,CAAC;QACF;YACE,KAAK,EAAE,CAAC,aAAa,CAAC;YACtB,KAAK,EAAE;gBACL,sBAAsB,EAAE,CAAC,OAAO,EAAE,GAAG,mBAAmB,CAAC;aAC1D;SACF;QACD;YACE,KAAK,EAAE,CAAC,eAAe,EAAE,kBAAkB,CAAC;YAC5C,KAAK,EAAE;gBACL,sBAAsB,EAAE,KAAK;aAC9B;SACF;KACiB,CAAC;AACvB,CAAC"}
+{"version":3,"file":"phaser.js","sourceRoot":"","sources":["../../../src/configs/eslint/phaser.ts"],"names":[],"mappings":"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"}

package/eslint-plugin-phaser/README.md

@@ -0,0 +1,19 @@
+# @codyswann/eslint-plugin-phaser
+
+ESLint 9 plugin enforcing Phaser 4 performance and lifecycle invariants that
+cannot be expressed as flat `no-restricted-syntax` selectors. It is wired into
+the Phaser stack automatically by `@codyswann/lisa/eslint/phaser`; you do not
+configure it directly.
+
+## Rules
+
+| Rule | What it catches |
+| --- | --- |
+| `no-create-in-update` | Creating GameObjects, tweens, timers, or `new Phaser.*` objects inside a Scene `update()` method (per-frame churn). Create in `create()` and pool/reuse. |
+| `no-allocation-in-update` | Heap allocations in `update()` — object/array literals, array-iteration chains (`.map`/`.filter`/`.reduce`/`.flatMap`), and `new` collections. Hoist scratch objects; iterate in place. |
+| `require-shutdown-cleanup` | A Scene that registers persistent external listeners (`this.input`/`this.scale`/`this.game.events`, `window`/`document`) without a cleanup path. Satisfied by a `shutdown()` method or a `this.events.once('shutdown', ...)` handler. |
+
+All three are scoped to `src/**` game code (relaxed in tests) by the Lisa Phaser
+ESLint config. Tests for these rules live in the Lisa repo under
+`tests/unit/config/eslint-plugin-phaser/` and run in CI via Vitest + ESLint's
+`RuleTester`.

package/eslint-plugin-phaser/index.js

@@ -0,0 +1,35 @@
+/**
+ * This file is managed by Lisa.
+ * Do not edit directly — changes will be overwritten on the next `lisa` run.
+ */
+
+/**
+ * ESLint plugin for Phaser 4 game-development standards
+ *
+ * Stateful rules that enforce Phaser 4 performance and lifecycle invariants that
+ * cannot be expressed as flat `no-restricted-syntax` selectors. Supports ESLint 9
+ * flat config. Wired into the Phaser stack via @codyswann/lisa/eslint/phaser.
+ *
+ * Rules:
+ * - no-create-in-update: no GameObject/tween/timer/Phaser creation in update()
+ * - no-allocation-in-update: no heap allocations in update()
+ * - require-shutdown-cleanup: persistent external listeners need a cleanup path
+ * @module eslint-plugin-phaser
+ */
+const noCreateInUpdate = require("./rules/no-create-in-update");
+const noAllocationInUpdate = require("./rules/no-allocation-in-update");
+const requireShutdownCleanup = require("./rules/require-shutdown-cleanup");
+
+const plugin = {
+  meta: {
+    name: "eslint-plugin-phaser",
+    version: "1.0.0",
+  },
+  rules: {
+    "no-create-in-update": noCreateInUpdate,
+    "no-allocation-in-update": noAllocationInUpdate,
+    "require-shutdown-cleanup": requireShutdownCleanup,
+  },
+};
+
+module.exports = plugin;

package/eslint-plugin-phaser/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@codyswann/eslint-plugin-phaser",
+  "version": "1.0.0",
+  "description": "ESLint plugin for Phaser 4 game-development standards",
+  "main": "index.js",
+  "publishConfig": { "access": "public" },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  }
+}

package/eslint-plugin-phaser/rules/no-allocation-in-update.js

@@ -0,0 +1,189 @@
+/**
+ * This file is managed by Lisa.
+ * Do not edit directly — changes will be overwritten on the next `lisa` run.
+ */
+
+/**
+ * ESLint rule: no-allocation-in-update
+ *
+ * Flags heap allocations directly inside a Scene's `update(time, delta)` method.
+ * `update` runs every frame, so allocations there create GC pressure that
+ * stutters the frame budget. Hoist scratch objects/arrays to fields created
+ * once in create(), and avoid per-frame array-iteration chains.
+ *
+ * Detected (lexically in the update method body, not in nested functions):
+ * - object literals  ({ ... })
+ * - array literals   ([ ... ])
+ * - array-iteration method calls (.map/.filter/.reduce/.flatMap/.flat/.concat/.slice)
+ * - new Array / Object / Map / Set / WeakMap / WeakSet / typed arrays
+ * @module eslint-plugin-phaser/rules/no-allocation-in-update
+ */
+
+const ARRAY_ALLOC_METHODS = new Set([
+  "map",
+  "filter",
+  "reduce",
+  "reduceRight",
+  "flatMap",
+  "flat",
+  "concat",
+  "slice",
+]);
+
+const COLLECTION_CTORS = new Set([
+  "Array",
+  "Object",
+  "Map",
+  "Set",
+  "WeakMap",
+  "WeakSet",
+  "Float32Array",
+  "Float64Array",
+  "Int32Array",
+  "Uint8Array",
+  "Uint16Array",
+  "Uint32Array",
+]);
+
+/**
+ * Resolve a property/method key node to its string name.
+ * @param {object} key - An Identifier or Literal key node
+ * @returns {string|null} The key name, or null if not resolvable
+ */
+function keyName(key) {
+  if (!key) return null;
+  if (key.type === "Identifier") return key.name;
+  if (key.type === "Literal") return String(key.value);
+  return null;
+}
+
+/**
+ * Whether a class extends a Phaser Scene (superclass name ends in "Scene", e.g.
+ * Phaser.Scene, Scene, BaseScene). Keeps this per-frame rule from firing on
+ * unrelated classes that merely happen to define an update() method.
+ * @param {object} classNode - A ClassDeclaration/ClassExpression node
+ * @returns {boolean} True if the class extends a Scene-like superclass
+ */
+function extendsScene(classNode) {
+  const sc = classNode.superClass;
+  if (!sc) return false;
+  if (sc.type === "Identifier") return /Scene$/.test(sc.name);
+  if (sc.type === "MemberExpression" && sc.property.type === "Identifier") {
+    return /Scene$/.test(sc.property.name);
+  }
+  return false;
+}
+
+/**
+ * Whether the nearest enclosing class extends a Phaser Scene.
+ * @param {object} node - Any node
+ * @returns {boolean} True if an enclosing class extends a Scene
+ */
+function enclosingSceneClass(node) {
+  const up = n => {
+    if (!n) return false;
+    if (n.type === "ClassDeclaration" || n.type === "ClassExpression") {
+      return extendsScene(n);
+    }
+    return up(n.parent);
+  };
+  return up(node.parent);
+}
+
+/**
+ * Determine whether a function node is the update() method of a Phaser Scene.
+ * @param {object} node - A function-like node
+ * @returns {boolean} True if it is a Scene update() method/field
+ */
+function isUpdateFunction(node) {
+  const parent = node.parent;
+  if (!parent) return false;
+  if (
+    (parent.type === "MethodDefinition" ||
+      parent.type === "PropertyDefinition") &&
+    parent.value === node &&
+    keyName(parent.key) === "update"
+  ) {
+    return enclosingSceneClass(node);
+  }
+  return false;
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow heap allocations (object/array literals, array-iteration chains, new collections) inside a Scene update() method",
+      category: "Best Practices",
+      recommended: true,
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      objectLiteral:
+        "Object literal allocated in update() (runs every frame). Hoist a reusable scratch object to a field set in create().",
+      arrayLiteral:
+        "Array literal allocated in update() (runs every frame). Hoist a reusable array, or iterate an existing one in place.",
+      arrayMethod:
+        "Array-iteration method '{{name}}' allocates in update() (runs every frame). Use a plain for-loop over the existing array.",
+      newCollection:
+        "new {{name}} allocated in update() (runs every frame). Create the collection once in create() and clear/reuse it.",
+    },
+  },
+
+  create(context) {
+    const fnStack = [];
+    const inUpdateBody = () =>
+      fnStack.length > 0 && fnStack[fnStack.length - 1];
+    const enter = node => fnStack.push(isUpdateFunction(node));
+    const exit = () => fnStack.pop();
+
+    return {
+      FunctionDeclaration: enter,
+      "FunctionDeclaration:exit": exit,
+      FunctionExpression: enter,
+      "FunctionExpression:exit": exit,
+      ArrowFunctionExpression: enter,
+      "ArrowFunctionExpression:exit": exit,
+
+      ObjectExpression(node) {
+        if (inUpdateBody())
+          context.report({ node, messageId: "objectLiteral" });
+      },
+
+      ArrayExpression(node) {
+        if (inUpdateBody()) context.report({ node, messageId: "arrayLiteral" });
+      },
+
+      CallExpression(node) {
+        if (!inUpdateBody()) return;
+        if (
+          node.callee.type === "MemberExpression" &&
+          node.callee.property.type === "Identifier" &&
+          ARRAY_ALLOC_METHODS.has(node.callee.property.name)
+        ) {
+          context.report({
+            node,
+            messageId: "arrayMethod",
+            data: { name: node.callee.property.name },
+          });
+        }
+      },
+
+      NewExpression(node) {
+        if (!inUpdateBody()) return;
+        if (
+          node.callee.type === "Identifier" &&
+          COLLECTION_CTORS.has(node.callee.name)
+        ) {
+          context.report({
+            node,
+            messageId: "newCollection",
+            data: { name: node.callee.name },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint-plugin-phaser/rules/no-create-in-update.js

@@ -0,0 +1,200 @@
+/**
+ * This file is managed by Lisa.
+ * Do not edit directly — changes will be overwritten on the next `lisa` run.
+ */
+
+/**
+ * ESLint rule: no-create-in-update
+ *
+ * Flags creation of GameObjects, tweens, timers, and Phaser objects inside a
+ * Scene's `update(time, delta)` method. `update` runs every frame; creating
+ * objects there churns the heap and stutters the frame budget. Create in
+ * `create()` and reuse (pool) instead.
+ *
+ * Detected (when lexically in the update method body, not in nested functions):
+ * - this.add.* / this.make.*               (GameObjectFactory / GameObjectCreator)
+ * - this.physics.add.*                      (Arcade factory)
+ * - this.tweens.add/addCounter/chain/create (Tween creation)
+ * - this.time.addEvent/delayedCall/addLoop  (Timer creation)
+ * - this.sound.add / this.anims.create / this.particles.add
+ * - new Phaser.*                            (Phaser object allocation)
+ * @module eslint-plugin-phaser/rules/no-create-in-update
+ */
+
+/**
+ * Resolve a property/method key node to its string name.
+ * @param {object} key - An Identifier or Literal key node
+ * @returns {string|null} The key name, or null if not resolvable
+ */
+function keyName(key) {
+  if (!key) return null;
+  if (key.type === "Identifier") return key.name;
+  if (key.type === "Literal") return String(key.value);
+  return null;
+}
+
+/**
+ * Decode a MemberExpression chain into its root node and ordered property names.
+ * @param {object} node - A MemberExpression node
+ * @returns {{root: object, props: (string|null)[]}} Root node and property names
+ */
+function memberInfo(node) {
+  const props = [];
+  /**
+   * Walk up the member chain, collecting property names.
+   * @param {object} cur - Current node in the chain
+   * @returns {object} The non-member root node
+   */
+  const walk = cur => {
+    if (cur && cur.type === "MemberExpression") {
+      props.unshift(
+        cur.property && cur.property.type === "Identifier"
+          ? cur.property.name
+          : null
+      );
+      return walk(cur.object);
+    }
+    return cur;
+  };
+  return { root: walk(node), props };
+}
+
+/**
+ * Whether a class extends a Phaser Scene (superclass name ends in "Scene", e.g.
+ * Phaser.Scene, Scene, BaseScene). Keeps this per-frame rule from firing on
+ * unrelated classes that merely happen to define an update() method.
+ * @param {object} classNode - A ClassDeclaration/ClassExpression node
+ * @returns {boolean} True if the class extends a Scene-like superclass
+ */
+function extendsScene(classNode) {
+  const sc = classNode.superClass;
+  if (!sc) return false;
+  if (sc.type === "Identifier") return /Scene$/.test(sc.name);
+  if (sc.type === "MemberExpression" && sc.property.type === "Identifier") {
+    return /Scene$/.test(sc.property.name);
+  }
+  return false;
+}
+
+/**
+ * Whether the nearest enclosing class extends a Phaser Scene.
+ * @param {object} node - Any node
+ * @returns {boolean} True if an enclosing class extends a Scene
+ */
+function enclosingSceneClass(node) {
+  const up = n => {
+    if (!n) return false;
+    if (n.type === "ClassDeclaration" || n.type === "ClassExpression") {
+      return extendsScene(n);
+    }
+    return up(n.parent);
+  };
+  return up(node.parent);
+}
+
+/**
+ * Determine whether a function node is the update() method of a Phaser Scene.
+ * @param {object} node - A function-like node
+ * @returns {boolean} True if it is a Scene update() method/field
+ */
+function isUpdateFunction(node) {
+  const parent = node.parent;
+  if (!parent) return false;
+  if (
+    (parent.type === "MethodDefinition" ||
+      parent.type === "PropertyDefinition") &&
+    parent.value === node &&
+    keyName(parent.key) === "update"
+  ) {
+    return enclosingSceneClass(node);
+  }
+  return false;
+}
+
+/**
+ * Patterns that create new objects, keyed by the leading `this.<segment>` chain.
+ * @param {(string|null)[]} props - Ordered property names from `this`
+ * @returns {boolean} True if the chain is a known creation call
+ */
+function isCreationChain(props) {
+  const [a, b] = props;
+  if (a === "add" || a === "make") return true;
+  if (a === "physics" && b === "add") return true;
+  if (
+    a === "tweens" &&
+    (b === "add" || b === "addCounter" || b === "chain" || b === "create")
+  ) {
+    return true;
+  }
+  if (
+    a === "time" &&
+    (b === "addEvent" || b === "delayedCall" || b === "addLoop")
+  )
+    return true;
+  if (a === "sound" && b === "add") return true;
+  if (a === "anims" && b === "create") return true;
+  if (a === "particles" && b === "add") return true;
+  return false;
+}
+
+module.exports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow creating GameObjects, tweens, timers, or Phaser objects inside a Scene update() method",
+      category: "Best Practices",
+      recommended: true,
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      createInUpdate:
+        "Do not create objects in update() — it runs every frame. Create in create() and pool/reuse (Group.get / killAndHide).",
+      newInUpdate:
+        "Do not allocate Phaser objects (new Phaser.*) in update() — it runs every frame. Hoist a reusable scratch instance to create().",
+    },
+  },
+
+  create(context) {
+    const fnStack = [];
+    const inUpdateBody = () =>
+      fnStack.length > 0 && fnStack[fnStack.length - 1];
+
+    /**
+     * Push function scope state on entry.
+     * @param {object} node - The function node being entered
+     * @returns {void}
+     */
+    const enter = node => fnStack.push(isUpdateFunction(node));
+    const exit = () => fnStack.pop();
+
+    return {
+      FunctionDeclaration: enter,
+      "FunctionDeclaration:exit": exit,
+      FunctionExpression: enter,
+      "FunctionExpression:exit": exit,
+      ArrowFunctionExpression: enter,
+      "ArrowFunctionExpression:exit": exit,
+
+      CallExpression(node) {
+        if (!inUpdateBody()) return;
+        if (node.callee.type !== "MemberExpression") return;
+        const { root, props } = memberInfo(node.callee);
+        if (root.type !== "ThisExpression") return;
+        if (isCreationChain(props)) {
+          context.report({ node, messageId: "createInUpdate" });
+        }
+      },
+
+      NewExpression(node) {
+        if (!inUpdateBody()) return;
+        if (node.callee.type !== "MemberExpression") return;
+        const { root } = memberInfo(node.callee);
+        if (root.type === "Identifier" && root.name === "Phaser") {
+          context.report({ node, messageId: "newInUpdate" });
+        }
+      },
+    };
+  },
+};