@moku-labs/game 0.8.0 → 0.9.0

package/dist/lint.mjs

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { readFileSync, statSync } from "node:fs";
 //#region src/lint.ts
 /**
 * @file The lint door of the engine (subpath `./lint`): an oxlint JS plugin named `moku-game` with
@@ -6,7 +7,9 @@ import path from "node:path";
 * (`"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.
+* default. The layout rules also take the folder of the game's layers (`root`) and the tsconfig
+* whose `paths` name the aliases (`tsconfig`). Only `node:path` and `node:fs` are imported; the
+* file is erasable TypeScript, so Node loads it unbuilt.
 */
 /** Tests and test helpers: no rule checks them by default. */
 const TESTS = [
@@ -16,23 +19,56 @@ const TESTS = [
 ];
 /** 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. */
+/**
+* The logic of a game: state, tables, the root flow in game.ts, core, nodes, flows, rules,
+* features, shared. `**` so `src/` matches too.
+*/
 const LOGIC = [
 	"**/state.ts",
 	"**/tables.ts",
-	"**/{nodes,flows,rules,features}/**"
+	"**/game.ts",
+	"**/{core,nodes,flows,rules,features,shared}/**"
 ];
-/** The options schema every rule shares; oxlint refuses options a rule has no schema for. */
+/** The effect side: moku plugins answer effects and may hold timers. */
+const EFFECT_SIDE = ["**/{plugin,plugins}/**"];
+/** The folders `test-suffix` reads. */
+const TEST_FOLDERS = ["**/tests/**", "**/__tests__/**"];
+/** The scope options every rule shares. */
+const SCOPE_PROPERTIES = {
+	files: {
+		type: "array",
+		items: { type: "string" }
+	},
+	ignores: {
+		type: "array",
+		items: { type: "string" }
+	}
+};
+/** The options schema of the rules without a layout; oxlint refuses options a rule has no schema for. */
 const SCHEMA = [{
+	type: "object",
+	properties: SCOPE_PROPERTIES,
+	additionalProperties: false
+}];
+/** The options schema of the layout rules: the scope, `root` and `tsconfig`. */
+const LAYOUT_SCHEMA = [{
 	type: "object",
 	properties: {
-		files: {
-			type: "array",
-			items: { type: "string" }
-		},
-		ignores: {
-			type: "array",
-			items: { type: "string" }
+		...SCOPE_PROPERTIES,
+		root: { type: "string" },
+		tsconfig: { type: "string" }
+	},
+	additionalProperties: false
+}];
+/** The options schema of `test-suffix`: the scope, `root` and `suffixes`. */
+const SUFFIX_SCHEMA = [{
+	type: "object",
+	properties: {
+		...SCOPE_PROPERTIES,
+		root: { type: "string" },
+		suffixes: {
+			type: "object",
+			additionalProperties: { type: "string" }
 		}
 	},
 	additionalProperties: false
@@ -74,6 +110,101 @@ 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=\"…\">.";
 /**
+* The aliases of the v15 layout, relative to the game root. The layout rules read them when the
+* tsconfig is missing, declares no `paths` or does not parse; a `paths` block replaces them whole.
+*/
+const V15_PATHS = {
+	"@core/*": ["core/*"],
+	"@shared": ["shared/index.ts"],
+	"@shared/rules": ["shared/rules/index.ts"],
+	"@features": ["features/index.ts"],
+	"@features/*": ["features/*/index.ts"],
+	"@plugins": ["plugins/index.ts"],
+	"@generated/*": ["generated/*"],
+	"@tests/*": ["tests/*"]
+};
+/** The engine and its subpaths: a package even when the tsconfig `paths` map it. */
+const ENGINE = /^@moku-labs\/game(?:\/|$)/;
+/** A specifier relative to the importing file, or an absolute path: never an alias. */
+const NOT_BARE = /^(?:\.{1,2}(?:\/|$)|\/)/;
+/** A specifier relative to the importing file. */
+const RELATIVE = /^\.{1,2}(?:\/|$)/;
+/** How many configs deep an `extends` chain is followed; a cycle ends there too. */
+const MAX_EXTENDS = 8;
+/** The stamp of a config file that is not there. */
+const MISSING = -1;
+/** A door file: the `index` of a unit, with or without its extension. */
+const INDEX_FILE = /^index(?:\.[jt]sx?)?$/;
+/** The root flow of a game, with or without its extension. */
+const GAME_FILE = /^game(?:\.[jt]sx?)?$/;
+/** The place of every path outside the layout. */
+const OTHER = {
+	layer: "other",
+	door: false
+};
+/** The layers each layer imports. `game.ts` imports every layer; the rest is not checked. */
+const LAYER_REACH = {
+	core: ["core", "generated"],
+	shared: [
+		"core",
+		"shared",
+		"generated"
+	],
+	features: [
+		"core",
+		"shared",
+		"features",
+		"generated"
+	],
+	plugins: [
+		"core",
+		"shared",
+		"plugins",
+		"generated"
+	]
+};
+/** The second sentence of every layer-imports report. */
+const LAYER_ORDER = "Order: core ← shared ← features ← game.ts; plugins import core and shared.";
+/** What feature-door says about a barrel imported below game.ts. */
+const BARREL_MESSAGE = "Door: only game.ts imports the @features and @plugins barrels.";
+/** The specifiers a rule imports besides its siblings, as written. */
+const RULE_ALIASES = /^@(?:core\/types|shared\/rules)$/;
+/** The files a rule imports besides its siblings, relative to the game root, any spelling. */
+const RULE_IMPORTS = [/^core\/types(?:\.[jt]sx?|\/.+)?$/, /^shared\/rules(?:\/index(?:\.[jt]sx?)?)?$/];
+/** What rules-siblings says. */
+const SIBLINGS_MESSAGE = "L4: a rule imports only its siblings in rules/, @core/types and @shared/rules: (state, input, tables) => result.";
+/** The suffix of each test kind folder. A table given in the options replaces it whole. */
+const TEST_SUFFIXES = {
+	"tests/e2e/": ".e2e.ts",
+	"tests/visual/": ".visual.ts",
+	"tests/editor/": ".editor.ts",
+	"__tests__/": ".test.ts",
+	"__tests__/unit/": ".test.ts",
+	"__tests__/integration/": ".test.ts",
+	"__tests__/isolated/": ".isolated.ts",
+	"__tests__/visual/": ".visual.ts"
+};
+/** A test root folder. */
+const TEST_ROOT = /^(?:tests|__tests__)$/;
+/** A kind folder key that names a test root itself: it holds only the files directly inside. */
+const TEST_ROOT_KEY = /(?:^|\/)(?:tests|__tests__)\/$/;
+/** The sub-folders of a test root whose files are helpers, not tests. */
+const HELPER_FOLDER = /^(?:helpers|fixtures|baselines)$/;
+/** A source file `test-suffix` reads. */
+const SCRIPT = /\.tsx?$/;
+/** The extension of a JSX test file: a `.ts` suffix of its kind takes an `x` for it. */
+const TSX_EXTENSION = ".tsx";
+/** The extension a suffix of a TypeScript kind ends with. */
+const TS_EXTENSION = ".ts";
+/** The folder of a colocated test root. */
+const COLOCATED_TESTS = "__tests__";
+/** Where a helper of a colocated `__tests__/` kind goes. */
+const COLOCATED_HELPERS = "__tests__/fixtures/";
+/** Where a helper of a root `tests/` kind goes. */
+const ROOT_HELPERS = "tests/helpers/";
+/** The test word a misnamed file may carry already: `board.test.ts` becomes `board.e2e.ts`. */
+const TEST_WORD = /\.(?:test|spec|e2e|visual|editor|isolated)$/;
+/**
 * Turn a glob into an anchored regular expression: `**`, `*`, `?` and one level of `{a,b}`.
 *
 * @param glob - A POSIX glob relative to the lint root.
@@ -118,6 +249,34 @@ function globChar(char) {
 	}
 }
 /**
+* A path with `/` between its parts on every platform.
+*
+* @param file - A path.
+* @returns The POSIX spelling.
+* @example
+* ```ts
+* toPosix("core/kit.ts"); // "core/kit.ts"
+* ```
+*/
+function toPosix(file) {
+	return file.split(path.sep).join("/");
+}
+/**
+* A path relative to a folder, when it lies inside it.
+*
+* @param folder - The absolute folder.
+* @param file - The absolute path.
+* @returns The relative POSIX path, or undefined for a path outside the folder.
+* @example
+* ```ts
+* insideOf("/game", "/game/core/kit.ts"); // "core/kit.ts"
+* ```
+*/
+function insideOf(folder, file) {
+	const relative = toPosix(path.relative(folder, file));
+	return relative === ".." || relative.startsWith("../") || path.isAbsolute(relative) ? void 0 : relative;
+}
+/**
 * Whether the rule checks the file the context lints: `files` match and no `ignores` match.
 *
 * @param context - The rule context.
@@ -128,7 +287,7 @@ 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 file = toPosix(path.relative(context.cwd, context.filename));
 	const matches = (globs) => globs.some((glob) => globToRegExp(glob).test(file));
 	return matches(files) && !matches(ignores);
 }
@@ -271,12 +430,12 @@ const nativeImports = importRule("No @moku-labs/system, @moku-labs/native or @ta
 	files: [
 		...LOGIC,
 		"**/kit.ts",
-		"**/game.ts"
+		"**/plugins/**"
 	],
 	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."
+	message: "L13: a native package is imported only where the platform is wired: platform-bridge.ts, native.ts or web/. 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.", {
@@ -290,15 +449,7 @@ const developmentImports = importRule("@moku-labs/editor and @moku-labs/game/con
 	]
 }, [{
 	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."
+	message: "Dev only: the dev page (web/main.ts, web/dev*.ts, web/editor*.ts), .dev modules and tests import the editor and /control."
 }]);
 /** L5: no module-scope `let` or `var` and no module-scope collection. */
 const noModuleState = {
@@ -323,7 +474,7 @@ const noModuleState = {
 		} };
 	}
 };
-/** L3: no device clock, no timers, no unseeded randomness in the logic. */
+/** L3: no device clock, no timers, no unseeded randomness in the logic. Plugins hold the timers. */
 const determinism = {
 	meta: {
 		type: "problem",
@@ -337,9 +488,14 @@ const determinism = {
 	* @returns The node visitors, none for a file out of scope.
 	*/
 	create(context) {
+		const ignores = [
+			...EFFECT_SIDE,
+			...DEV_MODULES,
+			...TESTS
+		];
 		if (!inScope(context, {
 			files: LOGIC,
-			ignores: [...DEV_MODULES, ...TESTS]
+			ignores
 		})) return {};
 		return {
 			MemberExpression: (node) => {
@@ -439,6 +595,799 @@ function isStaticKey(context, node, hops) {
 		default: return false;
 	}
 }
+/** Keys: a JSX key is a shape the project index reads, so `find` reaches it from a runtime key. */
+const staticKeys = {
+	meta: {
+		type: "problem",
+		docs: { description: "A JSX key is a literal, a template, props.id or props.<name>Key, or a call." },
+		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: ["**/*.tsx"],
+			ignores: TESTS
+		})) return {};
+		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
+			});
+		} };
+	}
+};
+/**
+* Where a JSON string that opens at `at` ends: the index after its closing quote.
+*
+* @param text - The text.
+* @param at - The index of the opening quote.
+* @returns The index after the closing quote, or the length for a string left open.
+* @example
+* ```ts
+* stringEnd('"a\\"b" x', 0); // 6
+* ```
+*/
+function stringEnd(text, at) {
+	let index = at + 1;
+	while (index < text.length && text.charAt(index) !== "\"") index += text.charAt(index) === "\\" ? 2 : 1;
+	return Math.min(index + 1, text.length);
+}
+/**
+* JSONC without its comments; a comment inside a string stays.
+*
+* @param text - The JSONC text.
+* @returns The text with every `//` and `/* *\/` comment turned into a space.
+* @example
+* ```ts
+* withoutComments('{ "a": "//" } // note'); // '{ "a": "//" }  '
+* ```
+*/
+function withoutComments(text) {
+	let json = "";
+	let index = 0;
+	while (index < text.length) if (text.charAt(index) === "\"") {
+		const end = stringEnd(text, index);
+		json += text.slice(index, end);
+		index = end;
+	} else if (text.startsWith("//", index)) {
+		const end = text.indexOf("\n", index);
+		json += " ";
+		index = end === -1 ? text.length : end;
+	} else if (text.startsWith("/*", index)) {
+		const end = text.indexOf("*/", index + 2);
+		json += " ";
+		index = end === -1 ? text.length : end + 2;
+	} else {
+		json += text.charAt(index);
+		index += 1;
+	}
+	return json;
+}
+/**
+* Whether the next character after the blanks from an index closes an object or an array.
+*
+* @param json - The text.
+* @param from - Where to look from.
+* @returns True before `}` or `]`.
+* @example
+* ```ts
+* closesNext("1,\n]", 2); // true
+* ```
+*/
+function closesNext(json, from) {
+	let index = from;
+	while (/\s/.test(json.charAt(index))) index += 1;
+	return json.charAt(index) === "}" || json.charAt(index) === "]";
+}
+/**
+* JSON without its trailing commas; a comma inside a string stays.
+*
+* @param json - JSON without comments.
+* @returns The text with every comma before a `}` or `]` dropped.
+* @example
+* ```ts
+* withoutTrailingCommas('{ "a": [1, 2,], }'); // '{ "a": [1, 2] }'
+* ```
+*/
+function withoutTrailingCommas(json) {
+	let strict = "";
+	let index = 0;
+	while (index < json.length) {
+		const char = json.charAt(index);
+		if (char === "\"") {
+			const end = stringEnd(json, index);
+			strict += json.slice(index, end);
+			index = end;
+		} else {
+			if (char !== "," || !closesNext(json, index + 1)) strict += char;
+			index += 1;
+		}
+	}
+	return strict;
+}
+/**
+* Whether a parsed JSON value is an object.
+*
+* @param value - The value.
+* @returns True for an object that is not an array.
+* @example
+* ```ts
+* isObject({ paths: {} }); // true
+* ```
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* A tsconfig as JSON: comments and trailing commas allowed, as TypeScript allows them.
+*
+* @param text - The text of the file.
+* @returns The object, or undefined when the text does not parse to one.
+* @example
+* ```ts
+* parseTsconfig('{ "extends": "./base.json", } // shared'); // { extends: "./base.json" }
+* ```
+*/
+function parseTsconfig(text) {
+	try {
+		const value = JSON.parse(withoutTrailingCommas(withoutComments(text)));
+		return isObject(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Read and parse a config file.
+*
+* @param file - The absolute path.
+* @returns The object, or undefined when the file cannot be read or does not parse.
+*/
+function readConfig(file) {
+	try {
+		return parseTsconfig(readFileSync(file, "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* The stamp of a file: its `mtimeMs`, or `MISSING`.
+*
+* @param file - The absolute path.
+* @returns The stamp.
+*/
+function stampOf(file) {
+	return statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? MISSING;
+}
+/**
+* The configs a tsconfig extends that the rules follow: relative and absolute paths, in the order
+* written. A package name ends the chain: lint resolves no node module. A path without `.json`
+* that is not there takes the extension, as TypeScript does.
+*
+* @param file - The absolute path of the config.
+* @param value - Its `extends`: a string, an array, or nothing.
+* @returns The absolute paths of the configs it extends.
+*/
+function parentsOf(file, value) {
+	return (Array.isArray(value) ? value : [value]).filter((name) => typeof name === "string").filter((name) => RELATIVE.test(name) || path.isAbsolute(name)).map((name) => path.resolve(path.dirname(file), name)).map((parent) => {
+		return parent.endsWith(".json") || stampOf(parent) !== MISSING ? parent : `${parent}.json`;
+	});
+}
+/**
+* Read a config and the configs it extends: the nearest `paths` and `baseUrl` win, and the later
+* entry of an `extends` array wins over the earlier one, as in TypeScript.
+*
+* @param file - The absolute path of the config.
+* @param depth - How many configs deep the chain is.
+* @param stamps - The files read and their stamps; this read adds to it.
+* @returns What the chain says, or the config that does not parse.
+*/
+function readChain(file, depth, stamps) {
+	const stamp = stampOf(file);
+	stamps.set(file, stamp);
+	if (stamp === MISSING) return {
+		paths: void 0,
+		baseUrl: void 0,
+		broken: void 0
+	};
+	const config = readConfig(file);
+	if (config === void 0) return {
+		paths: void 0,
+		baseUrl: void 0,
+		broken: file
+	};
+	const folder = path.dirname(file);
+	const options = isObject(config.compilerOptions) ? config.compilerOptions : {};
+	let paths = isObject(options.paths) ? {
+		entries: options.paths,
+		folder
+	} : void 0;
+	let baseUrl = typeof options.baseUrl === "string" ? path.resolve(folder, options.baseUrl) : void 0;
+	for (const parent of parentsOf(file, config.extends).toReversed()) {
+		if (paths !== void 0 && baseUrl !== void 0 || depth >= MAX_EXTENDS) break;
+		const inherited = readChain(parent, depth + 1, stamps);
+		if (inherited.broken !== void 0) return inherited;
+		paths ??= inherited.paths;
+		baseUrl ??= inherited.baseUrl;
+	}
+	return {
+		paths,
+		baseUrl,
+		broken: void 0
+	};
+}
+/**
+* How many `*` a key or a target holds.
+*
+* @param text - A key or a target of `paths`.
+* @returns The count.
+* @example
+* ```ts
+* starsOf("@features/*"); // 1
+* ```
+*/
+function starsOf(text) {
+	return text.split("*").length - 1;
+}
+/**
+* The targets of one key of `paths`, absolute: each string target with one `*` at most.
+*
+* @param base - The absolute folder the targets are relative to.
+* @param value - The value of the key.
+* @returns The targets, `*` kept.
+* @example
+* ```ts
+* targetsOf("/game", ["./core/*", 3]); // ["/game/core/*"]
+* ```
+*/
+function targetsOf(base, value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((target) => typeof target === "string" && starsOf(target) <= 1).map((target) => path.resolve(base, target));
+}
+/**
+* The patterns of a `paths` block: one per key with one `*` at most and a target.
+*
+* @param base - The absolute folder the targets are relative to.
+* @param paths - The `paths` block.
+* @returns The patterns, in the order of the keys.
+* @example
+* ```ts
+* patternsOf("/game", { "@core/*": ["./core/*"] }); // [{ prefix: "@core/", suffix: "", targets: ["/game/core/*"] }]
+* ```
+*/
+function patternsOf(base, paths) {
+	const patterns = [];
+	for (const [key, value] of Object.entries(paths)) {
+		const targets = targetsOf(base, value);
+		const star = key.indexOf("*");
+		if (targets.length === 0 || starsOf(key) > 1) continue;
+		patterns.push(star === -1 ? {
+			prefix: key,
+			targets
+		} : {
+			prefix: key.slice(0, star),
+			suffix: key.slice(star + 1),
+			targets
+		});
+	}
+	return patterns;
+}
+/**
+* Read a tsconfig for the layout rules: the patterns of its nearest `paths`, resolved against
+* `baseUrl` when one is set, else against the folder of the config that declares `paths`, as
+* TypeScript and the project index do.
+*
+* @param file - The absolute path of the tsconfig.
+* @returns The read, with the stamps of every config it touched.
+*/
+function readTsconfig(file) {
+	const stamps = /* @__PURE__ */ new Map();
+	const chain = readChain(file, 0, stamps);
+	const patterns = chain.paths === void 0 ? [] : patternsOf(chain.baseUrl ?? chain.paths.folder, chain.paths.entries);
+	return {
+		patterns: patterns.length === 0 ? void 0 : patterns,
+		broken: chain.broken,
+		stamps
+	};
+}
+/**
+* Whether every file of a read still has its stamp: one `statSync` per file.
+*
+* @param read - An earlier read.
+* @returns True when no config moved, appeared or vanished.
+*/
+function isFresh(read) {
+	for (const [file, stamp] of read.stamps) if (stampOf(file) !== stamp) return false;
+	return true;
+}
+/**
+* Whether a `*` key matches a specifier.
+*
+* @param prefix - The text before the `*`.
+* @param suffix - The text after it.
+* @param specifier - The module specifier.
+* @returns True when the specifier starts with the prefix and ends with the suffix.
+* @example
+* ```ts
+* matchesStar("@core/", "", "@core/kit"); // true
+* ```
+*/
+function matchesStar(prefix, suffix, specifier) {
+	return specifier.length >= prefix.length + suffix.length && specifier.startsWith(prefix) && specifier.endsWith(suffix);
+}
+/**
+* Whether a specifier is never an alias: a path relative to the importing file, an absolute path,
+* or the engine.
+*
+* @param specifier - The module specifier as written.
+* @returns True when no key of `paths` may match it.
+* @example
+* ```ts
+* isNeverAlias("@moku-labs/game/testing"); // true
+* ```
+*/
+function isNeverAlias(specifier) {
+	return NOT_BARE.test(specifier) || ENGINE.test(specifier);
+}
+/**
+* Whether a key of `paths` is a `*` key that matches a specifier with a longer prefix than the
+* best match so far.
+*
+* @param pattern - A key of `paths`.
+* @param best - The best `*` match so far, if any.
+* @param specifier - The module specifier.
+* @returns True when the key is the better match.
+* @example
+* ```ts
+* isBetterMatch({ prefix: "@core/", suffix: "", targets: ["/game/core/*"] }, undefined, "@core/kit"); // true
+* ```
+*/
+function isBetterMatch(pattern, best, specifier) {
+	const isLonger = best === void 0 || pattern.prefix.length > best.prefix.length;
+	return pattern.suffix !== void 0 && isLonger && matchesStar(pattern.prefix, pattern.suffix, specifier);
+}
+/**
+* The targets a specifier maps to, the way TypeScript maps it: a key without `*` equal to the
+* specifier wins; else the `*` key with the longest prefix, its `*` filled into every target. A
+* copy of `aliasTargets` in `src/project/aliases.ts`, which reads the tsconfig with TypeScript; this
+* file stays free of it. A behavioural unit test keeps the two in step.
+*
+* @param patterns - The aliases.
+* @param specifier - The module specifier as written.
+* @returns The absolute targets; `[]` for a relative specifier, the engine and no match.
+* @example
+* ```ts
+* targetsFor([{ prefix: "@core/", suffix: "", targets: ["/game/core/*"] }], "@core/kit"); // ["/game/core/kit"]
+* ```
+*/
+function targetsFor(patterns, specifier) {
+	if (isNeverAlias(specifier)) return [];
+	const exact = patterns.find((pattern) => pattern.suffix === void 0 && pattern.prefix === specifier);
+	if (exact !== void 0) return [...exact.targets];
+	let best;
+	for (const pattern of patterns) if (isBetterMatch(pattern, best, specifier)) best = pattern;
+	if (best === void 0) return [];
+	const hole = specifier.slice(best.prefix.length, specifier.length - best.suffix.length);
+	return best.targets.map((target) => target.replace("*", () => hole));
+}
+/**
+* The files a module specifier names through the aliases the layout rules read: the nearest
+* `paths` of the tsconfig and the configs it extends by relative path, else the v15 aliases under
+* the game root. A specifier is matched as TypeScript matches it; `@moku-labs/game` is a package
+* even when the paths map it. The project index maps a specifier the same way, and a unit test
+* keeps the two in step.
+*
+* @param tsconfig - The absolute path of the tsconfig.
+* @param root - The absolute folder of the layers; the v15 aliases resolve against it.
+* @param specifier - The module specifier as written.
+* @returns The absolute targets in the order of the tsconfig; `[]` for a relative specifier, the
+*   engine and a package.
+* @example
+* ```ts
+* // A game without a tsconfig reads the v15 aliases.
+* aliasTargetsOf("/game/tsconfig.json", "/game", "@features/orders"); // ["/game/features/orders/index.ts"]
+* ```
+*/
+function aliasTargetsOf(tsconfig, root, specifier) {
+	return targetsFor(readTsconfig(tsconfig).patterns ?? patternsOf(root, V15_PATHS), specifier);
+}
+/**
+* Whether the parts of a path below a unit folder name its door: nothing, or `index` alone.
+*
+* @param inner - The parts below the unit folder.
+* @returns True for the unit folder itself and its `index` file.
+* @example
+* ```ts
+* isDoor(["index.ts"]); // true
+* ```
+*/
+function isDoor(inner) {
+	return inner.length === 0 || inner.length === 1 && INDEX_FILE.test(inner[0] ?? "");
+}
+/**
+* The place of a path under `features/` or `plugins/`: the barrel, a unit and its door, or a
+* file that lies directly in the folder, which is outside the layout.
+*
+* @param layer - `features` or `plugins`.
+* @param below - The parts of the path below the layer folder.
+* @returns The place.
+* @example
+* ```ts
+* unitOf("features", ["orders", "index.ts"]); // { layer: "features", unit: "features/orders", door: true }
+* ```
+*/
+function unitOf(layer, below) {
+	const [name, ...inner] = below;
+	if (name === void 0 || inner.length === 0 && INDEX_FILE.test(name)) return {
+		layer,
+		unit: layer,
+		door: true
+	};
+	if (inner.length === 0 && path.extname(name) !== "") return OTHER;
+	return {
+		layer,
+		unit: `${layer}/${name}`,
+		door: isDoor(inner)
+	};
+}
+/**
+* Where a path lies in the layout of a game.
+*
+* @param root - The absolute folder of the layers.
+* @param file - The absolute path, with or without its extension.
+* @returns The place; `other` for a path outside the layout.
+* @example
+* ```ts
+* placeOf("/game", "/game/shared/index.ts"); // { layer: "shared", unit: "shared", door: true }
+* ```
+*/
+function placeOf(root, file) {
+	const relative = insideOf(root, file);
+	if (relative === void 0) return OTHER;
+	const [head = "", ...below] = relative.split("/");
+	switch (head) {
+		case "core": return {
+			layer: "core",
+			unit: "core",
+			door: false
+		};
+		case "shared": return {
+			layer: "shared",
+			unit: "shared",
+			door: isDoor(below)
+		};
+		case "features":
+		case "plugins": return unitOf(head, below);
+		case "generated":
+		case "tests": return {
+			layer: head,
+			door: false
+		};
+		default: return GAME_FILE.test(relative) ? {
+			layer: "game",
+			door: false
+		} : OTHER;
+	}
+}
+/**
+* Whether a place is one of the two barrels, `features/index.ts` or `plugins/index.ts`.
+*
+* @param place - A place.
+* @returns True for a barrel.
+* @example
+* ```ts
+* isBarrel({ layer: "features", unit: "features", door: true }); // true
+* ```
+*/
+function isBarrel(place) {
+	return (place.layer === "features" || place.layer === "plugins") && place.unit === place.layer;
+}
+/**
+* What a layout rule knows about the file the context lints: the layers, the aliases and where
+* the file lies.
+*
+* @param context - The rule context.
+* @param reads - The tsconfig reads of the rule, by absolute path.
+* @returns The layout.
+*/
+function layoutOf(context, reads) {
+	const [given] = context.options;
+	const root = path.resolve(context.cwd, given?.root ?? ".");
+	const tsconfig = path.resolve(context.cwd, given?.tsconfig ?? "tsconfig.json");
+	const file = path.resolve(context.cwd, context.filename);
+	let read = reads.get(tsconfig);
+	if (read === void 0 || !isFresh(read)) {
+		read = readTsconfig(tsconfig);
+		reads.set(tsconfig, read);
+	}
+	const broken = read.broken === void 0 ? void 0 : path.relative(context.cwd, read.broken);
+	return {
+		root,
+		folder: path.dirname(file),
+		importer: placeOf(root, file),
+		patterns: read.patterns ?? patternsOf(root, V15_PATHS),
+		problem: broken === void 0 ? void 0 : `Lint: ${toPosix(broken)} does not parse. The layout rules read the v15 aliases until it does.`
+	};
+}
+/**
+* The file an import names: a relative specifier joined to the folder of the file, an alias to its
+* first target.
+*
+* @param layout - The layout of the importing file.
+* @param specifier - The module specifier as written.
+* @returns The absolute target, or undefined for a package.
+*/
+function targetOf(layout, specifier) {
+	if (RELATIVE.test(specifier)) return path.resolve(layout.folder, specifier);
+	return targetsFor(layout.patterns, specifier)[0];
+}
+/**
+* Build a layout rule: it reads where the layers sit and the aliases, then judges each import,
+* export-from and `import()`, type-only statements too. The rule keeps the tsconfig it read for
+* the files of one lint run; the stamps of the configs keep the copy fresh.
+*
+* @param description - What the rule enforces.
+* @param defaults - The rule's default globs.
+* @param judge - The message for one import, or undefined when it passes.
+* @returns The rule.
+*/
+function layoutRule(description, defaults, judge) {
+	const reads = /* @__PURE__ */ new Map();
+	return {
+		meta: {
+			type: "problem",
+			docs: { description },
+			schema: LAYOUT_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 layout = layoutOf(context, reads);
+			const check = (node) => {
+				const specifier = specifierOf(node);
+				const message = specifier === void 0 ? void 0 : judge(layout, specifier);
+				if (message !== void 0) context.report({
+					node,
+					message
+				});
+			};
+			return {
+				Program: (node) => {
+					if (layout.problem !== void 0) context.report({
+						node,
+						message: layout.problem
+					});
+				},
+				ImportDeclaration: check,
+				ExportAllDeclaration: check,
+				ExportNamedDeclaration: check,
+				ImportExpression: check
+			};
+		}
+	};
+}
+/**
+* What rules-siblings says about one import of a rule: a sibling, `@core/types` and
+* `@shared/rules` pass, by alias or by relative path.
+*
+* @param layout - The layout of the rule's file.
+* @param specifier - The module specifier as written.
+* @returns The report, or undefined when the import passes.
+*/
+function siblingMessage(layout, specifier) {
+	if (specifier.startsWith("./") || RULE_ALIASES.test(specifier)) return void 0;
+	const target = targetOf(layout, specifier);
+	const relative = target === void 0 ? void 0 : insideOf(layout.root, target);
+	return RULE_IMPORTS.some((pattern) => pattern.test(relative ?? "")) ? void 0 : SIBLINGS_MESSAGE;
+}
+/**
+* What layer-imports says about one import: a layer imports the layers below it only.
+*
+* @param layout - The layout of the importing file.
+* @param specifier - The module specifier as written.
+* @returns The report, or undefined when the import passes.
+*/
+function layerMessage(layout, specifier) {
+	const reach = LAYER_REACH[layout.importer.layer];
+	const target = targetOf(layout, specifier);
+	if (reach === void 0 || target === void 0) return void 0;
+	const { layer } = placeOf(layout.root, target);
+	if (layer === "other" || reach.includes(layer)) return void 0;
+	const name = layer === "game" ? "game.ts" : layer;
+	return `Layers: ${layout.importer.layer} does not import ${name}. ${LAYER_ORDER}`;
+}
+/**
+* What feature-door says about an import that goes deep into another feature or plugin.
+*
+* @param importer - Where the importing file lies.
+* @param place - Where the import lands.
+* @returns The report, or undefined when the import lands on a door or in no unit of another.
+* @example
+* ```ts
+* deepMessage({ layer: "features", unit: "features/home", door: false }, { layer: "features", unit: "features/orders", door: false });
+* // "Door: another feature is imported from its index.ts only: @features/orders."
+* ```
+*/
+function deepMessage(importer, place) {
+	if (!(place.layer === "features" || place.layer === "plugins") || place.door || place.unit === importer.unit) return void 0;
+	return `Door: another ${place.layer === "features" ? "feature" : "plugin"} is imported from its index.ts only: @${place.unit}.`;
+}
+/**
+* What feature-door says about a unit that imports its own door.
+*
+* @param importer - Where the importing file lies.
+* @returns The report.
+* @example
+* ```ts
+* ownDoorMessage({ layer: "shared", unit: "shared", door: false });
+* // "Door: shared does not import its own index.ts. Import the file: ./flow/merge."
+* ```
+*/
+function ownDoorMessage(importer) {
+	return `Door: ${{
+		features: "a feature",
+		plugins: "a plugin"
+	}[importer.layer] ?? importer.layer} does not import its own index.ts. Import the file: ./flow/merge.`;
+}
+/**
+* What feature-door says about a relative import that leaves its unit.
+*
+* @param importer - Where the importing file lies.
+* @returns The report.
+* @example
+* ```ts
+* escapeMessage({ layer: "features", unit: "features/orders", door: false });
+* // "Door: an import that leaves features/orders is written as an alias: @features/<f>, @shared, @core/<file>."
+* ```
+*/
+function escapeMessage(importer) {
+	return `Door: an import that leaves ${importer.unit ?? importer.layer} is written as an alias: @features/<f>, @shared, @core/<file>.`;
+}
+/**
+* What feature-door says about an import of shared, a feature, a plugin or a barrel that lands in
+* the layout outside the barrels.
+*
+* @param importer - Where the importing file lies.
+* @param place - Where the import lands.
+* @param isRelative - True for a relative specifier.
+* @returns The report, or undefined when the import passes.
+* @example
+* ```ts
+* unitDoorMessage({ layer: "features", unit: "features", door: true }, { layer: "features", unit: "features/home", door: true }, true); // undefined
+* ```
+*/
+function unitDoorMessage(importer, place, isRelative) {
+	const deep = deepMessage(importer, place);
+	if (deep !== void 0) return deep;
+	if (place.unit === importer.unit) return place.door && !importer.door ? ownDoorMessage(importer) : void 0;
+	const staysInBarrel = isBarrel(importer) && place.layer === importer.layer;
+	return isRelative && !staysInBarrel ? escapeMessage(importer) : void 0;
+}
+/**
+* What feature-door says about one import of a unit: the barrels belong to game.ts, a unit does
+* not import its own door, another feature is reached through its door, and an import that
+* leaves the unit is written as an alias.
+*
+* @param layout - The layout of the importing file.
+* @param specifier - The module specifier as written.
+* @returns The report, or undefined when the import passes.
+*/
+function doorMessage(layout, specifier) {
+	const { importer } = layout;
+	const target = targetOf(layout, specifier);
+	if (importer.unit === void 0 || target === void 0) return void 0;
+	const place = placeOf(layout.root, target);
+	const isRelative = RELATIVE.test(specifier);
+	if (place.layer === "other") return void 0;
+	if (isBarrel(place)) return place.unit === importer.unit ? void 0 : BARREL_MESSAGE;
+	if (importer.layer === "core") return isRelative && place.layer !== "core" ? escapeMessage(importer) : void 0;
+	return unitDoorMessage(importer, place, isRelative);
+}
+/** L4: a rule imports only its siblings, the types of core and the rules of shared. */
+const rulesSiblings = layoutRule("A file under rules/ imports only its siblings, @core/types and @shared/rules.", {
+	files: ["**/rules/**"],
+	ignores: TESTS
+}, siblingMessage);
+/** Layers: core ← shared ← features ← game.ts; plugins import core and shared. */
+const layerImports = layoutRule("A layer imports only the layers below it: core ← shared ← features ← game.ts; plugins import core and shared.", {
+	files: ["**"],
+	ignores: [...TESTS, "**/generated/**"]
+}, layerMessage);
+/** Doors: a feature is imported from its index.ts, and the barrels only by game.ts. */
+const featureDoor = layoutRule("A feature is imported from its index.ts; the barrels only by game.ts; an import that leaves a feature is an alias.", {
+	files: ["**/{core,shared,features,plugins}/**"],
+	ignores: TESTS
+}, doorMessage);
+/**
+* The key of a suffix table as a folder: with a trailing `/`.
+*
+* @param key - A key of the table.
+* @returns The folder.
+* @example
+* ```ts
+* folderOf("tests/e2e"); // "tests/e2e/"
+* ```
+*/
+function folderOf(key) {
+	return key.endsWith("/") ? key : `${key}/`;
+}
+/**
+* The kind folder of the table that holds a folder: the nearest one, then the longest key. A key
+* that names a test root itself holds only the files directly inside.
+*
+* @param folder - The folder of the file, as `/a/b/`.
+* @param table - Kind folder to suffix.
+* @returns The kind, or undefined for a folder no key holds.
+* @example
+* ```ts
+* kindOf("/features/home/__tests__/unit/", { "__tests__/unit/": ".test.ts" })?.suffix; // ".test.ts"
+* ```
+*/
+function kindOf(folder, table) {
+	let best;
+	for (const [key, suffix] of Object.entries(table)) {
+		const kind = folderOf(key);
+		const at = folder.lastIndexOf(`/${kind}`);
+		const end = at + kind.length + 1;
+		const holds = at !== -1 && (end === folder.length || !TEST_ROOT_KEY.test(kind));
+		const isBetter = best === void 0 || end > best.end || end === best.end && kind.length > best.folder.length;
+		if (holds && isBetter) best = {
+			folder: kind,
+			suffix,
+			end
+		};
+	}
+	return best;
+}
+/**
+* Whether a test file is a helper: it lies in `helpers/`, `fixtures/` or `baselines/` somewhere
+* below its test root.
+*
+* @param folders - The folders of the file, from the game root.
+* @returns True for a helper, and for a file outside every test root.
+* @example
+* ```ts
+* isHelper(["tests", "visual", "baselines", "home"]); // true
+* ```
+*/
+function isHelper(folders) {
+	const first = folders.findIndex((folder) => TEST_ROOT.test(folder));
+	return first === -1 || folders.slice(first + 1).some((folder) => HELPER_FOLDER.test(folder));
+}
+/**
+* What test-suffix says about a file: a file in a test kind folder ends with that folder's suffix.
+*
+* @param file - The file, relative to the game root.
+* @param table - Kind folder to suffix.
+* @returns The report, or undefined for a file that passes or is not checked.
+* @example
+* ```ts
+* suffixMessage("tests/e2e/board.test.ts", { "tests/e2e/": ".e2e.ts" });
+* // "Tests: a file in tests/e2e/ ends with .e2e.ts. Rename board.test.ts to board.e2e.ts, or move a helper to tests/helpers/."
+* ```
+*/
+function suffixMessage(file, table) {
+	const name = path.posix.basename(file);
+	const extension = SCRIPT.exec(name)?.[0];
+	const folder = path.posix.dirname(file);
+	const kind = isHelper(folder.split("/")) ? void 0 : kindOf(`/${folder}/`, table);
+	if (extension === void 0 || kind === void 0) return void 0;
+	const suffix = extension === TSX_EXTENSION && kind.suffix.endsWith(TS_EXTENSION) ? `${kind.suffix}x` : kind.suffix;
+	if (name.endsWith(suffix)) return void 0;
+	const renamed = `${name.slice(0, -extension.length).replace(TEST_WORD, "")}${suffix}`;
+	const helpers = kind.folder.includes(COLOCATED_TESTS) ? COLOCATED_HELPERS : ROOT_HELPERS;
+	return `Tests: a file in ${kind.folder} ends with ${suffix}. Rename ${name} to ${renamed}, or move a helper to ${helpers}.`;
+}
 /**
 * The `moku-game` oxlint plugin. A game loads it by package name and turns its rules on.
 *
@@ -456,33 +1405,37 @@ const plugin = {
 		"no-module-state": noModuleState,
 		determinism,
 		"rules-siblings": rulesSiblings,
-		"static-keys": {
+		"static-keys": staticKeys,
+		"layer-imports": layerImports,
+		"feature-door": featureDoor,
+		"test-suffix": {
 			meta: {
 				type: "problem",
-				docs: { description: "A JSX key is a literal, a template, props.id or props.<name>Key, or a call." },
-				schema: SCHEMA
+				docs: { description: "A file in a test kind folder ends with its suffix: .e2e.ts, .visual.ts, .editor.ts, .test.ts, .isolated.ts." },
+				schema: SUFFIX_SCHEMA
 			},
 			/**
-			* Visit the file when the rule's globs match it.
+			* Visit the file when the rule's globs match it and its name misses the suffix.
 			*
 			* @param context - The rule context.
-			* @returns The node visitors, none for a file out of scope.
+			* @returns The node visitors, none for a file out of scope or named right.
 			*/
 			create(context) {
 				if (!inScope(context, {
-					files: ["**/*.tsx"],
-					ignores: TESTS
+					files: TEST_FOLDERS,
+					ignores: []
 				})) return {};
-				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
-					});
-				} };
+				const [given] = context.options;
+				const file = insideOf(path.resolve(context.cwd, given?.root ?? "."), path.resolve(context.cwd, context.filename));
+				const message = file === void 0 ? void 0 : suffixMessage(file, given?.suffixes ?? TEST_SUFFIXES);
+				if (message === void 0) return {};
+				return { Program: (node) => context.report({
+					node,
+					message
+				}) };
 			}
 		}
 	}
 };
 //#endregion
-export { plugin as default, globToRegExp };
+export { aliasTargetsOf, plugin as default, globToRegExp };