@moku-labs/game 0.4.4 → 0.4.6

package/README.md

@@ -192,8 +192,30 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | `@moku-labs/game/assets` | Node and Bun | Asset keys, the manifest, strings, the pack |
 | `@moku-labs/game/inspect` | anywhere | Read a running game |
 | `@moku-labs/game/control` | dev builds | Drive a running game |
+| `@moku-labs/game/lint` | oxlint | The game lint rules, as an oxlint JS plugin |
 | `@moku-labs/game/jsx-runtime`, `/jsx-dev-runtime` | anywhere | The JSX runtime. A game never imports it by hand. |
 
+### Lint for games
+
+`@moku-labs/game/lint` is an oxlint JS plugin, `moku-game`. It checks the engine rules in a game: lazy Pixi and Yoga, no native package in the logic, the editor only in dev files, no module-scope state, determinism and pure rules.
+
+```json
+// .oxlintrc.json
+{
+  "jsPlugins": ["@moku-labs/game/lint"],
+  "rules": {
+    "moku-game/lazy-imports": "error",
+    "moku-game/native-imports": "error",
+    "moku-game/dev-imports": "error",
+    "moku-game/no-module-state": "error",
+    "moku-game/determinism": "error",
+    "moku-game/rules-siblings": "error"
+  }
+}
+```
+
+Each rule takes `{ "files": [...], "ignores": [...] }`. The defaults follow the template layout. See [Lint for games](./docs/lint.md).
+
 ## Docs
 
 | Page | What is inside |
@@ -204,6 +226,7 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | [Doors for the editor](./docs/doors.md) | `/inspect` and `/control`, base sources and commands |
 | [Events](./docs/events.md) | Every event and its payload |
 | [Configuration](./docs/configuration.md) | Every config field and its default |
+| [Lint for games](./docs/lint.md) | The `moku-game` oxlint rules, their options and defaults |
 | [Testing](./docs/testing.md) | Headless and visual tests, all scripts, test layout, lint rules |
 | [`llms.txt`](./llms.txt) | The engine in one page, for an AI that writes a game |
 

package/dist/lint.d.mts

@@ -0,0 +1,79 @@
+//#region src/lint.d.ts
+/** The options every rule takes: which files it checks. A key given replaces the rule's default. */
+type GameLintOptions = {
+  /** Globs of the files the rule checks, relative to the directory oxlint runs in. */files?: string[]; /** Globs of the files the rule skips, even when `files` matches them. */
+  ignores?: string[];
+};
+/** The part of an ESTree node the rules read. oxlint and ESLint hand over full nodes. */
+type GameLintNode = {
+  readonly type: string;
+  readonly name?: string;
+  readonly value?: unknown;
+  readonly kind?: string;
+  readonly computed?: boolean;
+  readonly importKind?: string;
+  readonly exportKind?: string;
+  readonly source?: GameLintNode | null;
+  readonly body?: readonly GameLintNode[];
+  readonly declarations?: readonly GameLintNode[];
+  readonly declaration?: GameLintNode | null;
+  readonly init?: GameLintNode | null;
+  readonly callee?: GameLintNode;
+  readonly arguments?: readonly GameLintNode[];
+  readonly object?: GameLintNode;
+  readonly property?: GameLintNode;
+};
+/** The part of the rule context the rules read: where the file is, the options, the report. */
+type GameLintContext = {
+  readonly cwd: string;
+  readonly filename: string;
+  readonly options: readonly unknown[];
+  report(descriptor: {
+    node: GameLintNode;
+    message: string;
+  }): void;
+};
+/** A node visitor per ESTree node type. */
+type GameLintListeners = Record<string, (node: GameLintNode) => void>;
+/** One rule in the ESLint rule shape oxlint `jsPlugins` load. */
+type GameLintRule = {
+  readonly meta: {
+    readonly type: "problem";
+    readonly docs: {
+      readonly description: string;
+    };
+    readonly schema: readonly unknown[];
+  };
+  create(context: GameLintContext): GameLintListeners;
+};
+/** The plugin object: `moku-game` and its six rules. */
+type GameLintPlugin = {
+  readonly meta: {
+    readonly name: "moku-game";
+  };
+  readonly rules: Readonly<Record<GameLintRuleName, GameLintRule>>;
+};
+/** The rule names, without the `moku-game/` prefix. */
+type GameLintRuleName = "lazy-imports" | "native-imports" | "dev-imports" | "no-module-state" | "determinism" | "rules-siblings";
+/**
+ * Turn a glob into an anchored regular expression: `**`, `*`, `?` and one level of `{a,b}`.
+ *
+ * @param glob - A POSIX glob relative to the lint root.
+ * @returns The expression a relative POSIX path is tested against.
+ * @example
+ * ```ts
+ * globToRegExp("{nodes,rules}/*.ts").test("rules/merge.ts"); // true
+ * ```
+ */
+declare function globToRegExp(glob: string): RegExp;
+/**
+ * The `moku-game` oxlint plugin. A game loads it by package name and turns its rules on.
+ *
+ * @example
+ * ```json
+ * { "jsPlugins": ["@moku-labs/game/lint"], "rules": { "moku-game/lazy-imports": "error" } }
+ * ```
+ */
+declare const plugin: GameLintPlugin;
+//#endregion
+export { GameLintContext, GameLintListeners, GameLintNode, GameLintOptions, GameLintPlugin, GameLintRule, GameLintRuleName, plugin as default, globToRegExp };

package/dist/lint.mjs

@@ -0,0 +1,360 @@
+import path from "node:path";
+//#region src/lint.ts
+/**
+* @file The lint door of the engine (subpath `./lint`): an oxlint JS plugin named `moku-game` with
+* the rules a game carries. A game loads it by package name in `.oxlintrc.json`
+* (`"jsPlugins": ["@moku-labs/game/lint"]`) and turns the rules on as `moku-game/<rule>`. The rules
+* use the ESLint rule API, so ESLint 9 loads the same object. Every rule takes
+* `[{ files, ignores }]`: globs relative to the directory oxlint runs in; a key given replaces the
+* default. Only `node:path` is imported; the file is erasable TypeScript, so Node loads it unbuilt.
+*/
+/** Tests and test helpers: no rule checks them by default. */
+const TESTS = [
+	"tests/**",
+	"**/__tests__/**",
+	"**/*.{test,spec}.{ts,tsx}"
+];
+/** Dev modules: a `.dev` module is wired into the editor only. */
+const DEV_MODULES = ["**/*.dev.{ts,tsx}"];
+/** The logic of a game: state, tables, nodes, flows, rules, features. `**` so `src/` matches too. */
+const LOGIC = [
+	"**/state.ts",
+	"**/tables.ts",
+	"**/{nodes,flows,rules,features}/**"
+];
+/** The options schema every rule shares; oxlint refuses options a rule has no schema for. */
+const SCHEMA = [{
+	type: "object",
+	properties: {
+		files: {
+			type: "array",
+			items: { type: "string" }
+		},
+		ignores: {
+			type: "array",
+			items: { type: "string" }
+		}
+	},
+	additionalProperties: false
+}];
+/** Bases of a timer call that still reach the global timer. */
+const GLOBAL_OBJECT = /^(?:globalThis|window|self)$/;
+/** The global timers of L3. */
+const TIMER = /^set(?:Timeout|Interval)$/;
+/** The forbidden member reads of L3: object, property and the fix. */
+const CLOCK_READS = [
+	{
+		object: "Math",
+		property: "random",
+		message: "L3: use an rng stream: rng.stream(id)."
+	},
+	{
+		object: "Date",
+		property: "now",
+		message: "L3: use `now` from the node context."
+	},
+	{
+		object: "performance",
+		property: "now",
+		message: "L3: use `now` from the node context."
+	}
+];
+/** The collections a module may not hold at module scope (L5). */
+const COLLECTION = /^(?:Map|Set|WeakMap|WeakSet)$/;
+/**
+* Turn a glob into an anchored regular expression: `**`, `*`, `?` and one level of `{a,b}`.
+*
+* @param glob - A POSIX glob relative to the lint root.
+* @returns The expression a relative POSIX path is tested against.
+* @example
+* ```ts
+* globToRegExp("{nodes,rules}/*.ts").test("rules/merge.ts"); // true
+* ```
+*/
+function globToRegExp(glob) {
+	let source = "";
+	let index = 0;
+	while (index < glob.length) {
+		const char = glob.charAt(index);
+		if (glob.startsWith("**/", index)) {
+			source += "(?:.*/)?";
+			index += 3;
+		} else if (glob.startsWith("**", index)) {
+			source += ".*";
+			index += 2;
+		} else {
+			source += globChar(char);
+			index += 1;
+		}
+	}
+	return new RegExp(`^${source}$`);
+}
+/**
+* The expression for one glob character other than `**`.
+*
+* @param char - The character.
+* @returns Its regular-expression source.
+*/
+function globChar(char) {
+	switch (char) {
+		case "*": return "[^/]*";
+		case "?": return "[^/]";
+		case "{": return "(?:";
+		case "}": return ")";
+		case ",": return "|";
+		default: return char.replaceAll(/[$()+.[\\\]^|]/g, String.raw`\$&`);
+	}
+}
+/**
+* Whether the rule checks the file the context lints: `files` match and no `ignores` match.
+*
+* @param context - The rule context.
+* @param defaults - The rule's default globs.
+* @returns True when the rule applies.
+*/
+function inScope(context, defaults) {
+	const [given] = context.options;
+	const files = given?.files ?? defaults.files;
+	const ignores = given?.ignores ?? defaults.ignores;
+	const file = path.relative(context.cwd, context.filename).split(path.sep).join("/");
+	const matches = (globs) => globs.some((glob) => globToRegExp(glob).test(file));
+	return matches(files) && !matches(ignores);
+}
+/**
+* The specifier of an import node, when it is a string literal.
+*
+* @param node - An import, export-from or `import()` node.
+* @returns The specifier, or undefined for a computed `import()` or a local export.
+*/
+function specifierOf(node) {
+	const value = node.source?.type === "Literal" ? node.source.value : void 0;
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* Whether a static import or export carries types only: `import type` or `export type`.
+* `import { type A }` keeps a side-effect import under `verbatimModuleSyntax`, so it counts as a value.
+*
+* @param node - A static import or export node.
+* @returns True for a type-only statement.
+*/
+function isTypeOnly(node) {
+	return node.importKind === "type" || node.exportKind === "type";
+}
+/**
+* Build a rule that reports imports of forbidden specifiers.
+*
+* @param description - What the rule enforces.
+* @param defaults - The rule's default globs.
+* @param checks - The forbidden patterns and their messages.
+* @param lazy - True for L2: `import()` and type-only statements pass.
+* @returns The rule.
+*/
+function importRule(description, defaults, checks, lazy = false) {
+	return {
+		meta: {
+			type: "problem",
+			docs: { description },
+			schema: SCHEMA
+		},
+		/**
+		* Visit the file when the rule's globs match it.
+		*
+		* @param context - The rule context.
+		* @returns The node visitors, none for a file out of scope.
+		*/
+		create(context) {
+			if (!inScope(context, defaults)) return {};
+			const check = (node) => {
+				const name = specifierOf(node);
+				const hit = name === void 0 ? void 0 : checks.find((item) => item.pattern.test(name));
+				if (hit === void 0) return;
+				if (lazy && isTypeOnly(node)) return;
+				context.report({
+					node,
+					message: hit.message
+				});
+			};
+			const listeners = {
+				ImportDeclaration: check,
+				ExportAllDeclaration: check,
+				ExportNamedDeclaration: check
+			};
+			if (!lazy) listeners.ImportExpression = check;
+			return listeners;
+		}
+	};
+}
+/**
+* The name of a member's property: `a.b` and `a["b"]`.
+*
+* @param node - A MemberExpression.
+* @returns The property name, or undefined for a computed non-literal key.
+*/
+function propertyName(node) {
+	const key = node.property;
+	if (key === void 0) return void 0;
+	if (!node.computed) return key.name;
+	return typeof key.value === "string" ? key.value : void 0;
+}
+/**
+* Report the module-scope state of one top-level statement (L5).
+*
+* @param context - The rule context.
+* @param statement - A statement of the Program body.
+*/
+function reportModuleState(context, statement) {
+	const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+	if (declaration?.type !== "VariableDeclaration") return;
+	if (declaration.kind === "let" || declaration.kind === "var") {
+		context.report({
+			node: declaration,
+			message: "L5: no module-scope state. State lives in player and session."
+		});
+		return;
+	}
+	for (const declarator of declaration.declarations ?? []) {
+		const init = declarator.init;
+		if (init?.type === "NewExpression" && COLLECTION.test(init.callee?.name ?? "")) context.report({
+			node: init,
+			message: "L5: no module-scope collections. Create them inside a function."
+		});
+	}
+}
+/**
+* Whether a call's callee reaches a global timer: `setTimeout(...)`, `globalThis.setInterval(...)`.
+*
+* @param callee - The callee of a CallExpression.
+* @returns True for a timer.
+*/
+function isTimer(callee) {
+	if (callee?.type === "Identifier") return TIMER.test(callee.name ?? "");
+	if (callee?.type !== "MemberExpression") return false;
+	return GLOBAL_OBJECT.test(callee.object?.name ?? "") && TIMER.test(propertyName(callee) ?? "");
+}
+/** L2: static value imports of the packages the engine loads lazily. */
+const lazyImports = importRule("No static import of pixi.js or yoga-layout; import() and import type pass.", {
+	files: ["**"],
+	ignores: TESTS
+}, [{
+	pattern: /^pixi\.js(?:\/|$)/,
+	message: "L2: the renderer loads Pixi lazily. Draw with the engine's tags, use import() or import type."
+}, {
+	pattern: /^yoga-layout(?:\/|$)/,
+	message: "L2: the ui plugin loads Yoga lazily. Use import() or import type."
+}], true);
+/** L13: native packages stay out of the engine-facing layers. */
+const nativeImports = importRule("No @moku-labs/system, @moku-labs/native or @tauri-apps/* in the engine-facing layers.", {
+	files: [
+		...LOGIC,
+		"**/kit.ts",
+		"**/game.ts"
+	],
+	ignores: [...DEV_MODULES, ...TESTS]
+}, [{
+	pattern: /^(?:@moku-labs\/(?:system|native)(?:\/|$)|@tauri-apps\/)/,
+	message: "L13: only platform-bridge.ts, native.ts and web/ import a native package. Pass a PlatformProvider."
+}]);
+/** Dev only: the editor and the control door stay in dev files. */
+const developmentImports = importRule("@moku-labs/editor and @moku-labs/game/control only in dev files and tests.", {
+	files: ["**"],
+	ignores: [
+		"web/main.ts",
+		"web/dev*.ts",
+		"web/editor*.ts",
+		...DEV_MODULES,
+		...TESTS
+	]
+}, [{
+	pattern: /^@moku-labs\/(?:editor(?:\/|$)|game\/control$)/,
+	message: "Dev only: web/main.ts, web/dev*.ts, web/editor*.ts, .dev modules and tests import the editor and /control."
+}]);
+/** L4: a rule imports only its siblings. */
+const rulesSiblings = importRule("A file under rules/ imports only its siblings.", {
+	files: ["**/rules/**"],
+	ignores: TESTS
+}, [{
+	pattern: /^(?!\.\/)/,
+	message: "L4: a rule imports only its siblings in rules/: (state, input, tables) => result."
+}]);
+/**
+* The `moku-game` oxlint plugin. A game loads it by package name and turns its rules on.
+*
+* @example
+* ```json
+* { "jsPlugins": ["@moku-labs/game/lint"], "rules": { "moku-game/lazy-imports": "error" } }
+* ```
+*/
+const plugin = {
+	meta: { name: "moku-game" },
+	rules: {
+		"lazy-imports": lazyImports,
+		"native-imports": nativeImports,
+		"dev-imports": developmentImports,
+		"no-module-state": {
+			meta: {
+				type: "problem",
+				docs: { description: "No module-scope let or var and no module-scope Map, Set, WeakMap, WeakSet." },
+				schema: SCHEMA
+			},
+			/**
+			* Visit the file when the rule's globs match it.
+			*
+			* @param context - The rule context.
+			* @returns The node visitors, none for a file out of scope.
+			*/
+			create(context) {
+				if (!inScope(context, {
+					files: ["**"],
+					ignores: TESTS
+				})) return {};
+				return { Program: (program) => {
+					for (const statement of program.body ?? []) reportModuleState(context, statement);
+				} };
+			}
+		},
+		determinism: {
+			meta: {
+				type: "problem",
+				docs: { description: "No Math.random, Date.now, performance.now, new Date(), setTimeout or setInterval in the logic." },
+				schema: SCHEMA
+			},
+			/**
+			* Visit the file when the rule's globs match it.
+			*
+			* @param context - The rule context.
+			* @returns The node visitors, none for a file out of scope.
+			*/
+			create(context) {
+				if (!inScope(context, {
+					files: LOGIC,
+					ignores: [...DEV_MODULES, ...TESTS]
+				})) return {};
+				return {
+					MemberExpression: (node) => {
+						const property = propertyName(node);
+						const read = CLOCK_READS.find((item) => item.object === node.object?.name && item.property === property);
+						if (read !== void 0) context.report({
+							node,
+							message: read.message
+						});
+					},
+					NewExpression: (node) => {
+						if (node.callee?.name === "Date" && (node.arguments ?? []).length === 0) context.report({
+							node,
+							message: "L3: use `now` from the node context."
+						});
+					},
+					CallExpression: (node) => {
+						if (isTimer(node.callee)) context.report({
+							node,
+							message: "L3: store the moment in player, await fx(schedule(moment))."
+						});
+					}
+				};
+			}
+		},
+		"rules-siblings": rulesSiblings
+	}
+};
+//#endregion
+export { plugin as default, globToRegExp };

package/llms.txt

@@ -11,6 +11,7 @@ Facts: Bun only. ESM only. `"sideEffects": false`. `pixi.js` `^8.0.0` is a peer
 - `@moku-labs/game/assets` (node and bun only): the asset key scanner, the production packer and the string compiler. The package bin `moku-game-assets` runs it.
 - `@moku-labs/game/inspect`: the read door of the editor, safe in a production build. See "Doors for the editor".
 - `@moku-labs/game/control`: the write door of the editor, dev builds only. See "Doors for the editor".
+- `@moku-labs/game/lint`: the oxlint JS plugin `moku-game` with the game lint rules. See "Lint for games".
 - `@moku-labs/game/fonts/*`: the shipped MSDF body font and its licence. See "Fonts".
 - `@moku-labs/game/jsx-runtime` and `@moku-labs/game/jsx-dev-runtime`: what `"jsxImportSource": "@moku-labs/game"` resolves to. A game never imports them by hand.
 
@@ -130,6 +131,33 @@ type NodeContext = {
 - A node never calls `app.model`, `app.clock` or `app.time`. Everything outside logic goes through `fx`.
 - A timer is a moment stored in player state. How long is left is computed from `now`.
 
+## Lint for games
+
+`.oxlintrc.json` of a game (oxlint 1.86.0 or later):
+
+```json
+{
+  "jsPlugins": ["@moku-labs/game/lint"],
+  "rules": {
+    "moku-game/lazy-imports": "error",
+    "moku-game/native-imports": "error",
+    "moku-game/dev-imports": "error",
+    "moku-game/no-module-state": "error",
+    "moku-game/determinism": "error",
+    "moku-game/rules-siblings": "error"
+  }
+}
+```
+
+- `moku-game/lazy-imports` (L2): no static value import of `pixi.js` or `yoga-layout`. `import type` and `import()` pass. Default files `**`.
+- `moku-game/native-imports` (L13): no `@moku-labs/system`, `@moku-labs/native`, `@tauri-apps/*` in the logic, `kit.ts` and `game.ts`. Use `platform-bridge.ts`.
+- `moku-game/dev-imports`: `@moku-labs/editor` and `@moku-labs/game/control` only in `web/main.ts`, `web/dev*.ts`, `web/editor*.ts`, `*.dev.ts(x)` and tests.
+- `moku-game/no-module-state` (L5): no module-scope `let` or `var`, no module-scope `new Map/Set/WeakMap/WeakSet`. Default files `**`.
+- `moku-game/determinism` (L3): no `Math.random`, `Date.now`, `performance.now`, `new Date()`, `setTimeout`, `setInterval` in the logic. `new Date(now)` passes.
+- `moku-game/rules-siblings` (L4): a file under `rules/` imports only `./` siblings.
+- Logic = `**/state.ts`, `**/tables.ts`, `**/{nodes,flows,rules,features}/**`. Tests (`tests/**`, `**/__tests__/**`, `*.test.ts`) are skipped by every rule.
+- Every rule takes `["error", { "files": [...], "ignores": [...] }]`. Globs are relative to the directory oxlint runs in; a key given replaces the default.
+
 ## Minimal game
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/game",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "2D puzzle game engine on TypeScript and PixiJS, built on @moku-labs/core.",
   "type": "module",
   "sideEffects": false,
@@ -27,6 +27,10 @@
       "types": "./dist/control.d.mts",
       "default": "./dist/control.mjs"
     },
+    "./lint": {
+      "types": "./dist/lint.d.mts",
+      "default": "./dist/lint.mjs"
+    },
     "./jsx-runtime": {
       "types": "./dist/jsx-runtime.d.mts",
       "default": "./dist/jsx-runtime.mjs"
@@ -124,6 +128,7 @@
     "globals": "17.4.0",
     "jiti": "2.6.1",
     "lefthook": "2.1.1",
+    "oxlint": "1.86.0",
     "pixi.js": "8.21.0",
     "playwright-core": "1.60.0",
     "publint": "0.3.21",