@moku-labs/game 0.5.0 → 0.7.0

package/README.md

@@ -194,11 +194,12 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 | `@moku-labs/game/control` | dev builds | Drive a running game |
 | `@moku-labs/game/hot` | the Bun dev server | The `bunfig.toml` plugin that hot swaps views. See [Hot swap](./docs/hot-swap.md) |
 | `@moku-labs/game/lint` | oxlint | The game lint rules, as an oxlint JS plugin |
+| `@moku-labs/game/project` | Node and Bun | Where every engine id of a game is defined, line fresh at the call. The bin `moku-game-index`. See [Project index](./docs/project-index.md) |
 | `@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.
+`@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, pure rules and JSX keys the project index can follow.
 
 ```json
 // .oxlintrc.json
@@ -210,7 +211,8 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
     "moku-game/dev-imports": "error",
     "moku-game/no-module-state": "error",
     "moku-game/determinism": "error",
-    "moku-game/rules-siblings": "error"
+    "moku-game/rules-siblings": "error",
+    "moku-game/static-keys": "error"
   }
 }
 ```
@@ -229,6 +231,7 @@ Each rule takes `{ "files": [...], "ignores": [...] }`. The defaults follow the
 | [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 |
+| [Project index](./docs/project-index.md) | `openProject`, the key scheme, `find` and `watch`, the `moku-game-index` bin |
 | [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 |
 
@@ -265,7 +268,7 @@ A save of a logic file reloads the page. What swaps and what reloads: [docs/hot-
 
 - **Node `>= 24`** and **Bun `>= 1.3.14`**. Use `bun` only.
 - **TypeScript** in strict mode, with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`.
-- **`pixi.js` `^8.0.0`** as a peer dependency. `playwright-core` for visual tests and `sharp` for the asset pack are optional peers. `yoga-layout` is loaded lazily by `ui`. The string compiler uses `@formatjs/icu-messageformat-parser` at build time only.
+- **`pixi.js` `^8.0.0`** as a peer dependency. `playwright-core` for visual tests, `sharp` for the asset pack and `typescript` for the project index are optional peers. `yoga-layout` is loaded lazily by `ui`. The string compiler uses `@formatjs/icu-messageformat-parser` at build time only.
 - **[`@moku-labs/core`](https://github.com/moku-labs/core)** is the kernel. **[`@moku-labs/common`](https://github.com/moku-labs/common)** brings `log` and `env`.
 
 ## License

package/bin/moku-game-index.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCli } from "../dist/project.mjs";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/lint.d.mts

@@ -6,8 +6,8 @@ type GameLintOptions = {
 };
 /** 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 type: string; /** A string on an `Identifier`; the `JSXIdentifier` node on a `JSXAttribute`. */
+  readonly name?: string | GameLintNode;
   readonly value?: unknown;
   readonly kind?: string;
   readonly computed?: boolean;
@@ -22,12 +22,33 @@ type GameLintNode = {
   readonly arguments?: readonly GameLintNode[];
   readonly object?: GameLintNode;
   readonly property?: GameLintNode;
+  readonly expression?: GameLintNode;
+  readonly expressions?: readonly GameLintNode[];
 };
-/** The part of the rule context the rules read: where the file is, the options, the report. */
+/** One declaration of a name, as the scope manager of oxlint and ESLint hands it over. */
+type GameLintDefinition = {
+  /** `Variable`, `Parameter`, `ImportBinding`, `FunctionName` and the other ESLint kinds. */readonly type: string; /** The declarator of a `Variable`: its `init` is the value. */
+  readonly node: GameLintNode; /** The declaration of a `Variable`: its `kind` is `const`, `let` or `var`. */
+  readonly parent?: GameLintNode | null;
+};
+/** The part of a scope the rules read: the names it declares and the scope around it. */
+type GameLintScope = {
+  readonly set: ReadonlyMap<string, {
+    readonly defs: readonly GameLintDefinition[];
+  }>;
+  readonly upper?: GameLintScope | null;
+};
+/**
+ * The part of the rule context the rules read: where the file is, the options, the scopes of the
+ * file and the report.
+ */
 type GameLintContext = {
   readonly cwd: string;
   readonly filename: string;
   readonly options: readonly unknown[];
+  readonly sourceCode: {
+    getScope(node: GameLintNode): GameLintScope;
+  };
   report(descriptor: {
     node: GameLintNode;
     message: string;
@@ -46,7 +67,7 @@ type GameLintRule = {
   };
   create(context: GameLintContext): GameLintListeners;
 };
-/** The plugin object: `moku-game` and its six rules. */
+/** The plugin object: `moku-game` and its seven rules. */
 type GameLintPlugin = {
   readonly meta: {
     readonly name: "moku-game";
@@ -54,7 +75,7 @@ type GameLintPlugin = {
   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";
+type GameLintRuleName = "lazy-imports" | "native-imports" | "dev-imports" | "no-module-state" | "determinism" | "rules-siblings" | "static-keys";
 /**
  * Turn a glob into an anchored regular expression: `**`, `*`, `?` and one level of `{a,b}`.
  *
@@ -76,4 +97,4 @@ declare function globToRegExp(glob: string): RegExp;
  */
 declare const plugin: GameLintPlugin;
 //#endregion
-export { GameLintContext, GameLintListeners, GameLintNode, GameLintOptions, GameLintPlugin, GameLintRule, GameLintRuleName, plugin as default, globToRegExp };
+export { GameLintContext, GameLintDefinition, GameLintListeners, GameLintNode, GameLintOptions, GameLintPlugin, GameLintRule, GameLintRuleName, GameLintScope, plugin as default, globToRegExp };

package/dist/lint.mjs

@@ -62,6 +62,18 @@ const CLOCK_READS = [
 /** The collections a module may not hold at module scope (L5). */
 const COLLECTION = /^(?:Map|Set|WeakMap|WeakSet)$/;
 /**
+* A key-carrying prop the project index fills a key from: `id`, or a name that ends in `Key`. The
+* index holds its own copy; a behavioural unit test keeps the two in step: the rule accepts
+* `props.<name>` exactly when the index turns it into a `{<name>}` hole.
+*/
+const KEY_PROP = /^(?:id|\w+Key)$/;
+/** The wrappers a key is read through, as the index reads them: casts, parentheses, `?.` chains. */
+const KEY_WRAPPER = /^(?:TSAsExpression|TSSatisfiesExpression|TSNonNullExpression|TSTypeAssertion|ParenthesizedExpression|ChainExpression)$/;
+/** How many `const` initializers a key name is followed through. */
+const KEY_HOPS = 3;
+/** What static-keys says about a key the project index cannot follow. */
+const STATIC_KEYS_MESSAGE = "Keys: a JSX key must be a literal, a template, or props.id / props.<name>Key. Pass the key in as a prop: <X id=\"…\">.";
+/**
 * Turn a glob into an anchored regular expression: `**`, `*`, `?` and one level of `{a,b}`.
 *
 * @param glob - A POSIX glob relative to the lint root.
@@ -185,6 +197,18 @@ function importRule(description, defaults, checks, lazy = false) {
 	};
 }
 /**
+* The name a node carries: the name of an `Identifier`, the name of the `JSXIdentifier` of a
+* `JSXAttribute`.
+*
+* @param node - Any node.
+* @returns The name, or undefined for a node without one.
+*/
+function nameOf(node) {
+	const name = node?.name;
+	if (typeof name === "string") return name;
+	return typeof name?.name === "string" ? name.name : void 0;
+}
+/**
 * The name of a member's property: `a.b` and `a["b"]`.
 *
 * @param node - A MemberExpression.
@@ -193,7 +217,7 @@ function importRule(description, defaults, checks, lazy = false) {
 function propertyName(node) {
 	const key = node.property;
 	if (key === void 0) return void 0;
-	if (!node.computed) return key.name;
+	if (!node.computed) return nameOf(key);
 	return typeof key.value === "string" ? key.value : void 0;
 }
 /**
@@ -214,7 +238,7 @@ function reportModuleState(context, statement) {
 	}
 	for (const declarator of declaration.declarations ?? []) {
 		const init = declarator.init;
-		if (init?.type === "NewExpression" && COLLECTION.test(init.callee?.name ?? "")) context.report({
+		if (init?.type === "NewExpression" && COLLECTION.test(nameOf(init.callee) ?? "")) context.report({
 			node: init,
 			message: "L5: no module-scope collections. Create them inside a function."
 		});
@@ -227,9 +251,9 @@ function reportModuleState(context, statement) {
 * @returns True for a timer.
 */
 function isTimer(callee) {
-	if (callee?.type === "Identifier") return TIMER.test(callee.name ?? "");
+	if (callee?.type === "Identifier") return TIMER.test(nameOf(callee) ?? "");
 	if (callee?.type !== "MemberExpression") return false;
-	return GLOBAL_OBJECT.test(callee.object?.name ?? "") && TIMER.test(propertyName(callee) ?? "");
+	return GLOBAL_OBJECT.test(nameOf(callee.object) ?? "") && 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.", {
@@ -276,6 +300,145 @@ const rulesSiblings = importRule("A file under rules/ imports only its siblings.
 	pattern: /^(?!\.\/)/,
 	message: "L4: a rule imports only its siblings in rules/: (state, input, tables) => result."
 }]);
+/** L5: no module-scope `let` or `var` and no module-scope collection. */
+const noModuleState = {
+	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);
+		} };
+	}
+};
+/** L3: no device clock, no timers, no unseeded randomness in the logic. */
+const 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 === nameOf(node.object) && item.property === property);
+				if (read !== void 0) context.report({
+					node,
+					message: read.message
+				});
+			},
+			NewExpression: (node) => {
+				if (nameOf(node.callee) === "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))."
+				});
+			}
+		};
+	}
+};
+/**
+* Whether a value an attribute holds is a node: the `JSXExpressionContainer` of `key={…}`.
+*
+* @param value - The `value` of a node.
+* @returns True for a node.
+*/
+function isNode(value) {
+	return typeof value === "object" && value !== null && "type" in value;
+}
+/**
+* A key expression without the wrappers around it: `props.id as string` and `props?.id` read
+* `props.id`.
+*
+* @param node - The key expression.
+* @returns The expression inside.
+*/
+function unwrapKey(node) {
+	let inner = node;
+	while (inner !== null && inner !== void 0 && KEY_WRAPPER.test(inner.type)) inner = inner.expression;
+	return inner;
+}
+/**
+* The declaration of a name where it is used, read scope by scope outwards.
+*
+* @param context - The rule context.
+* @param identifier - The name where it is used.
+* @returns Its first declaration, or undefined for a name the file does not declare.
+*/
+function definitionOf(context, identifier) {
+	const name = nameOf(identifier) ?? "";
+	for (let scope = context.sourceCode.getScope(identifier); scope; scope = scope.upper) {
+		const variable = scope.set.get(name);
+		if (variable !== void 0) return variable.defs[0];
+	}
+}
+/** The declarations a key name is left to the index for: `--check` lists what it cannot read. */
+const OUT_OF_REACH = /^(?:Parameter|ImportBinding)$/;
+/**
+* Whether a key name is one the project index reads: a `const` whose value is a static key, or a
+* name out of reach here (a parameter, an import, a global), which `--check` lists when the index
+* cannot read it.
+*
+* @param context - The rule context.
+* @param identifier - The name.
+* @param hops - How many `const` initializers were followed to reach it.
+* @returns False for a `let`, a `var`, a `const` whose value the index cannot follow, and a
+*   function, a class or a catch parameter.
+*/
+function isStaticName(context, identifier, hops) {
+	const definition = definitionOf(context, identifier);
+	if (definition === void 0 || OUT_OF_REACH.test(definition.type) || hops >= KEY_HOPS) return true;
+	if (definition.type !== "Variable") return false;
+	return definition.parent?.kind === "const" && isStaticKey(context, definition.node.init, hops + 1);
+}
+/**
+* Whether a key expression is one the project index reads: a literal, a template of static parts,
+* `props.id` or `props.<name>Key`, a call, or a name that holds one.
+*
+* @param context - The rule context.
+* @param node - The key expression.
+* @param hops - How many `const` initializers were followed to reach it.
+* @returns False for an element access, `??`, `||`, `&&`, `?:` and any other member.
+*/
+function isStaticKey(context, node, hops) {
+	const expression = unwrapKey(node);
+	switch (expression?.type) {
+		case "Literal": return typeof expression.value === "string" || typeof expression.value === "number";
+		case "TemplateLiteral": return (expression.expressions ?? []).every((part) => isStaticKey(context, part, hops));
+		case "MemberExpression": return !expression.computed && expression.object?.type === "Identifier" && KEY_PROP.test(propertyName(expression) ?? "");
+		case "Identifier": return isStaticName(context, expression, hops);
+		case "CallExpression": return true;
+		default: return false;
+	}
+}
 /**
 * The `moku-game` oxlint plugin. A game loads it by package name and turns its rules on.
 *
@@ -290,10 +453,13 @@ const plugin = {
 		"lazy-imports": lazyImports,
 		"native-imports": nativeImports,
 		"dev-imports": developmentImports,
-		"no-module-state": {
+		"no-module-state": noModuleState,
+		determinism,
+		"rules-siblings": rulesSiblings,
+		"static-keys": {
 			meta: {
 				type: "problem",
-				docs: { description: "No module-scope let or var and no module-scope Map, Set, WeakMap, WeakSet." },
+				docs: { description: "A JSX key is a literal, a template, props.id or props.<name>Key, or a call." },
 				schema: SCHEMA
 			},
 			/**
@@ -304,56 +470,18 @@ const plugin = {
 			*/
 			create(context) {
 				if (!inScope(context, {
-					files: ["**"],
+					files: ["**/*.tsx"],
 					ignores: TESTS
 				})) return {};
-				return { Program: (program) => {
-					for (const statement of program.body ?? []) reportModuleState(context, statement);
+				return { JSXAttribute: (node) => {
+					const container = isNode(node.value) ? node.value : void 0;
+					if (nameOf(node) === "key" && container?.type === "JSXExpressionContainer" && !isStaticKey(context, container.expression, 0)) context.report({
+						node,
+						message: STATIC_KEYS_MESSAGE
+					});
 				} };
 			}
-		},
-		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