@moku-labs/game 0.6.0 → 0.7.0

package/README.md

@@ -199,7 +199,7 @@ createApp({ plugins: [...screen, effectsPlugin, audioPlugin, platformPlugin] });
 
 ### 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
@@ -211,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"
   }
 }
 ```

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

package/dist/project.d.mts

@@ -3,7 +3,7 @@
  * @file project — the public types of the project index: the options of `openProject`, the index
  * it holds, the anchors of a key, the fresh lines `find` answers and the handle itself. The index
  * maps every engine id of a game (flows, nodes, features, scenes, projections, emitters, text
- * styles, styles and JSX keys) to anchors: a path plus a binding, a key or a component. It never
+ * styles, styles, components and JSX keys) to anchors: a path plus a binding, a key or a component. It never
  * holds a line number; `find` reads the line from the file as it is on disk at the call. No type
  * here names a `typescript` type, so the shipped declarations need no TypeScript.
  */
@@ -24,7 +24,8 @@ type ProjectOptions = {
 };
 /**
  * How a JSX key is written: a string literal `key="hudRow"`, a template `` key={`${id}Picture`} ``,
- * any other expression `key={id}`, or a literal `id=` prop on a component (`id="settingsBoard"`).
+ * any other expression `key={id}`, or a literal key-carrying prop on a component: `id=`, or a prop
+ * whose name ends in `Key` (`id="settingsBoard"`, `amountKey="giftReward"`).
  *
  * @example
  * ```ts
@@ -44,11 +45,20 @@ type JsxKind = "literal" | "template" | "idProp" | "ident";
  */
 type Anchor = {
   /** The file, root-relative POSIX. */path: string; /** The const, function or export the definition is bound to. */
-  binding?: string; /** The property or attribute key: a text style key, the `name` of a projection, a JSX key. */
-  key?: string; /** JSX: the component an `id=` prop sits on, or the component an `{id}` pattern is written in. */
+  binding?: string;
+  /**
+   * The property or attribute key: a text style key, the `name` of a projection, a JSX key, or
+   * the property a style function builds a style under (`icon` of `roundStylesOf`).
+   */
+  key?: string;
+  /**
+   * JSX: the component a key-carrying prop sits on, or the component a `{id}` or `{amountKey}`
+   * pattern is written in.
+   */
   component?: string; /** JSX only: how the key is written. */
   kind?: JsxKind; /** JSX templates and identifiers: the literal head of the pattern, `card` for `card*Picture`. */
-  stem?: string;
+  stem?: string; /** JSX idProp: the prop the value sits on, `id` or `amountKey`. */
+  prop?: string;
 };
 /**
  * The index of one game at one moment: every key with its anchors, every indexed file with its
@@ -65,8 +75,8 @@ type ProjectIndex = {
   revision: string; /** The asset manifest, root-relative, when that file exists. */
   manifest?: string;
   /**
-   * Every key: where it is defined (`def`), where its binding is used (`uses`, nodes and styles,
-   * one level), and `conflict` when a key other than `jsx:` is defined twice.
+   * Every key: where it is defined (`def`), where its binding is used (`uses`, nodes, styles and
+   * components, one level), and `conflict` when a key other than `jsx:` is defined twice.
    */
   symbols: Record<string, {
     def: Anchor[];
@@ -108,7 +118,8 @@ type ProjectChange = {
 /**
  * One answer of `find`: the anchor with its line read from the file now. Lines and columns are
  * 1-based; the end column is exclusive. A binding answers its declaration statement, a text style
- * key its property, a JSX key the line of its attribute with the whole element as the range.
+ * key its property, a style built in a function each of its style calls, a JSX key the line of its
+ * attribute with the whole element as the range.
  *
  * @example
  * ```ts
@@ -142,9 +153,9 @@ type ProjectApi = {
    * Answers where a key is defined, with lines read from the file on disk now. A file whose bytes
    * changed since the index was built is parsed again for the answer; the index itself stays as
    * it is until the next watch batch. A JSX key the game reports at run time also finds the
-   * patterns it was built from: exact keys first, then `{id}` patterns filled with a literal
-   * `id=` prop (both the pattern and the prop come back), then `*` patterns. An unknown key
-   * answers `[]`.
+   * patterns it was built from: exact keys first, then `{id}` and `{amountKey}` patterns filled
+   * with a literal prop of the same name on their component (both the pattern and the prop come
+   * back), then `*` patterns. An unknown key answers `[]`.
    *
    * @param key - An engine id: `node:board/merge`, `flow:board`, `textStyle:ui.title`, `jsx:card2Picture`.
    * @returns One entry per place, in the order above; `broken` when the file does not parse now.
@@ -153,7 +164,7 @@ type ProjectApi = {
    * // The editor jumps to the node the flow view clicked, and to the X of the settings board.
    * (await project.find("node:board/merge"))[0]?.line; // 17, in "nodes/merge.ts"
    * (await project.find("jsx:settingsBoardClose")).map(found => `${found.path}:${found.line}`);
-   * // ["features/ui/kit.tsx:844", "features/settings/settings.tsx:301"]
+   * // ["features/ui/kit.tsx:844", "features/settings/settings.tsx:290"]
    * ```
    */
   find(key: string): Promise<Found[]>;