@moku-labs/game 0.14.12 → 0.14.13

package/dist/features-DowEilZm.mjs

@@ -0,0 +1,266 @@
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+//#region src/project/features.ts
+/** The folders that hold one kind of code or resource of a feature: never a sub-feature, whatever they hold. */
+const KIND_FOLDER = /^(?:flow|views|rules|styles|motion|world|effects|nodes|assets|strings|content|__tests__)$/;
+/** The file names of a door, in the order a door is looked for. */
+const DOORS = ["index.ts", "index.tsx"];
+/** A `//` comment to the end of the line or a block comment, whichever starts first. */
+const COMMENT = /\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
+/** An import declaration: the text up to its source (the clause and `from`), and the source. */
+const IMPORT = /\bimport\b([^;"']*)["']([^"']+)["']/g;
+/** A `features: [ … ]` property, key bare or quoted, up to the first `]`. */
+const LISTING = /(?:\bfeatures|"features"|'features')\s*:\s*\[([^\]]*)\]/g;
+/** An identifier. */
+const IDENTIFIER = /[$A-Z_a-z][\w$]*/g;
+/** A source naming a folder beside the door: `./<folder>`, `./<folder>/index`, either with `.ts`, `.tsx` or `.js`. */
+const FOLDER_SOURCE = /^\.\/([^/]+?)(?:\/index)?(?:\.(?:tsx?|js))?$/;
+/**
+* Finds every feature owner of a game: each folder of the features folder, and inside an owner each folder (not a kind
+* folder such as `flow/` or `assets/`) with a door `index.ts` and resources of its own, at any depth. Depth first, a
+* parent before its children, siblings sorted as the asset scanner sorts features. Reads folders only, never a door.
+*
+* @param root - The game folder.
+* @param features - The name of the folder that holds the features. Default `"features"`.
+* @returns The owners; none when the features folder is missing.
+* @throws {Error} When one feature name belongs to two folders; the message names both.
+* @example
+* ```ts
+* // tests/fixtures/episodes-game
+* findFeatureOwners("tests/fixtures/episodes-game").map(owner => owner.dir);
+* // ["features/episodes", "features/episodes/ep01", "features/episodes/ep02",
+* //  "features/episodes/episodes-kit", "features/home"]
+* ```
+*/
+function findFeatureOwners(root, features = "features") {
+	return walk(root, features, false);
+}
+/**
+* Finds every feature folder lint and the project index treat as a unit: the owners of `findFeatureOwners`, and
+* inside an owner each code-only folder with a door that the owner's door imports from `./<folder>` and lists in
+* `features: [...]`. Reads the owners' doors as text, never with TypeScript. Same order and the same name check as
+* `findFeatureOwners`. A code-only sub-feature declares no sub-features: its own folders are never searched.
+*
+* @param root - The game folder.
+* @param features - The name of the folder that holds the features. Default `"features"`.
+* @returns The owners and the code-only sub-features; none when the features folder is missing.
+* @throws {Error} When one feature name belongs to two folders; the message names both.
+* @example
+* ```ts
+* // features/episodes/index.ts imports { toolsFeature } from "./tools" and lists it in features: [...];
+* // features/episodes/tools/ has an index.ts and code only.
+* findFeatureUnits("game").find(unit => unit.name === "tools");
+* // { name: "tools", dir: "features/episodes/tools", parent: "episodes", depth: 1, resources: { assets: false, strings: false } }
+* ```
+*/
+function findFeatureUnits(root, features = "features") {
+	return walk(root, features, true);
+}
+/**
+* The owner a root-relative path belongs to: the one with the longest `dir` that is the path or a folder above it.
+*
+* @param owners - The owners of `findFeatureOwners`, or the units of `findFeatureUnits`.
+* @param file - A root-relative POSIX path, a file or a folder, with or without an extension.
+* @returns The deepest owner holding it; `undefined` outside every owner.
+* @example
+* ```ts
+* ownerOf([{ dir: "features/episodes" }, { dir: "features/episodes/ep01" }], "features/episodes/ep01/flow/story.ts")?.dir; // "features/episodes/ep01"
+* ```
+*/
+function ownerOf(owners, file) {
+	let deepest;
+	for (const owner of owners) if ((file === owner.dir || file.startsWith(`${owner.dir}/`)) && (deepest === void 0 || owner.dir.length > deepest.dir.length)) deepest = owner;
+	return deepest;
+}
+/**
+* Walks the features folder: each of its folders is an owner, and below each owner its sub-features.
+*
+* @param root - The game folder.
+* @param features - The features folder, relative to the root.
+* @param units - True to add the code-only sub-features the owners' doors list.
+* @returns The owners (and units), depth first, siblings sorted.
+* @throws {Error} When one feature name belongs to two folders.
+*/
+function walk(root, features, units) {
+	const top = path.join(root, features);
+	const base = features.replaceAll("\\", "/");
+	const found = [];
+	for (const entry of sorted(list(top).filter((item) => item.isDirectory()))) {
+		const folder = path.join(top, entry.name);
+		const entries = list(folder);
+		collect(found, {
+			name: entry.name,
+			dir: path.posix.join(base, entry.name),
+			depth: 0,
+			resources: resourcesOf(entries)
+		}, folder, entries, units);
+	}
+	checkNames(found);
+	return found;
+}
+/**
+* Adds an owner, then its sub-features in sibling order: an owner sub-feature with its own sub-features, a code-only
+* one its door lists as a leaf.
+*
+* @param found - The list to add to, in walk order.
+* @param owner - The owner to add.
+* @param folder - The owner's folder on disk.
+* @param entries - The entries of that folder.
+* @param units - True to add the code-only sub-features the door lists.
+*/
+function collect(found, owner, folder, entries, units) {
+	found.push(owner);
+	const listed = units ? listedIn(folder, entries) : [];
+	for (const child of sorted(entries.filter((entry) => isCandidate(entry)))) {
+		const childFolder = path.join(folder, child.name);
+		const childEntries = list(childFolder);
+		if (doorOf(childEntries) === void 0) continue;
+		const resources = resourcesOf(childEntries);
+		const sub = {
+			name: child.name,
+			dir: `${owner.dir}/${child.name}`,
+			parent: owner.name,
+			depth: owner.depth + 1
+		};
+		if (resources.assets || resources.strings) collect(found, {
+			...sub,
+			resources
+		}, childFolder, childEntries, units);
+		else if (listed.includes(child.name)) found.push({
+			...sub,
+			resources
+		});
+	}
+}
+/**
+* Tells whether a folder entry may be a sub-feature: a folder, not a kind folder, not a dot folder.
+*
+* @param entry - An entry of an owner's folder.
+* @returns True when the entry is worth a look.
+*/
+function isCandidate(entry) {
+	return entry.isDirectory() && !KIND_FOLDER.test(entry.name) && !entry.name.startsWith(".");
+}
+/**
+* Lists a folder; a folder that is missing, a file or unreadable counts as empty.
+*
+* @param folder - The folder on disk.
+* @returns Its entries.
+*/
+function list(folder) {
+	try {
+		return readdirSync(folder, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+}
+/**
+* Sorts folder entries by name, with the comparator the asset scanner sorts features with.
+*
+* @param entries - The entries.
+* @returns A sorted copy.
+*/
+function sorted(entries) {
+	return entries.toSorted((left, right) => left.name.localeCompare(right.name));
+}
+/**
+* The door of a folder: `index.ts`, else `index.tsx`.
+*
+* @param entries - The entries of the folder.
+* @returns The door's file name; `undefined` without one.
+*/
+function doorOf(entries) {
+	return DOORS.find((door) => entries.some((entry) => entry.isFile() && entry.name === door));
+}
+/**
+* What a folder brings of its own.
+*
+* @param entries - The entries of the folder.
+* @returns Whether it has `assets/` or `assets.ts`, and whether it has `strings/`.
+*/
+function resourcesOf(entries) {
+	const has = (name, folder) => entries.some((entry) => entry.name === name && (folder ? entry.isDirectory() : entry.isFile()));
+	return {
+		assets: has("assets", true) || has("assets.ts", false),
+		strings: has("strings", true)
+	};
+}
+/**
+* The folders an owner's door imports and lists in `features: [...]`. A door that cannot be read lists nothing.
+*
+* @param folder - The owner's folder on disk.
+* @param entries - The entries of that folder.
+* @returns The listed folder names.
+*/
+function listedIn(folder, entries) {
+	const door = doorOf(entries);
+	if (door === void 0) return [];
+	try {
+		return listedFolders(readFileSync(path.join(folder, door), "utf8"));
+	} catch {
+		return [];
+	}
+}
+/**
+* The folders a door imports from `./<folder>` (not `import type`) and names in a `features: [...]` array, comments
+* removed first. A text scan, not a parse.
+*
+* @param doorText - The text of the door.
+* @returns The folder names, in import order.
+* @example listedFolders('import { kitFeature } from "./kit";\nexport const f = defineFeature("a", { features: [kitFeature] });'); // ["kit"]
+*/
+function listedFolders(doorText) {
+	const text = doorText.replaceAll(COMMENT, "");
+	const listed = /* @__PURE__ */ new Set();
+	for (const [, items = ""] of text.matchAll(LISTING)) for (const [identifier] of items.matchAll(IDENTIFIER)) listed.add(identifier);
+	const folders = /* @__PURE__ */ new Set();
+	for (const [, head = "", source = ""] of text.matchAll(IMPORT)) {
+		const folder = FOLDER_SOURCE.exec(source)?.[1];
+		const clause = head.trim().replace(/from$/, "");
+		if (folder === void 0 || /^type\s/.test(clause)) continue;
+		if (localNames(clause).some((name) => listed.has(name))) folders.add(folder);
+	}
+	return [...folders];
+}
+/**
+* The local names an import clause binds at runtime: the default import, the namespace import and each named
+* specifier that is not `type`-only (`a as b` gives `b`).
+*
+* @param clause - The text between `import` and `from`.
+* @returns The local names.
+* @example localNames("main, { a as b, type c, d }"); // ["b", "d", "main"]
+*/
+function localNames(clause) {
+	const open = clause.indexOf("{");
+	const close = clause.indexOf("}");
+	const named = open === -1 ? [] : clause.slice(open + 1, close).split(",");
+	const outside = open === -1 ? clause : clause.slice(0, open) + clause.slice(close + 1);
+	const names = [];
+	for (const part of [...named, ...outside.split(",")]) {
+		const words = part.trim().split(/\s+/);
+		if (words[0] === "type" && words.length > 1) continue;
+		const name = words.at(-1);
+		if (name) names.push(name);
+	}
+	return names;
+}
+/**
+* Refuses a feature name used by two folders, before anything is returned. The first folder is the earlier one in
+* walk order.
+*
+* @param found - The owners (and units), in walk order.
+* @throws {Error} For the first name met twice; the message names both folders and a free name.
+*/
+function checkNames(found) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const owner of found) {
+		const first = seen.get(owner.name);
+		if (first !== void 0) {
+			const parent = owner.parent ?? first.parent;
+			throw new Error(`[game] features: the feature name "${owner.name}" is taken by two folders: ${first.dir} and ${owner.dir}.\n  A feature is named like its folder, once in the game. Name a shared sub-feature after its parent: ${parent}-${owner.name}.`);
+		}
+		seen.set(owner.name, owner);
+	}
+}
+//#endregion
+export { findFeatureUnits as n, ownerOf as r, findFeatureOwners as t };

package/dist/{headless-CMHNsKjW.d.mts → headless-cFveciuY.d.mts}

@@ -1,4 +1,4 @@
-import { Mt as JournalEntry, Pt as RouteStep, Vt as Answer, Zt as Json, dt as Api$1, gn as Api, jt as FlowState, ln as RngState } from "./types-BjTtGSFb.mjs";
+import { Ar as Api, Cr as RngState, Gn as RouteStep, Hn as FlowState, Un as JournalEntry, bn as Api$1, er as Answer, ur as Json } from "./types-BGcda5Le.mjs";
 
 //#region src/plugins/flow/headless.d.ts
 /**

package/dist/hot.d.mts

@@ -16,7 +16,8 @@ type HotOptions = {
    * The files that get the footer. Default: `.tsx` files, `styles.ts`, `view.ts`,
    * `animations.ts`, `effects.ts`, any `.ts` directly in a `styles/`, `motion/`, `effects/` or
    * `views/` folder, and in `world/projections/` or `world/layout/`,
-   * `generated/strings.<locale>.ts`, and the stamp module `.moku/assets-stamp.ts`. Bun runs it as
+   * `generated/strings.<locale>.ts` and `generated/strings.<feature>.<locale>.ts`, and the stamp
+   * module `.moku/assets-stamp.ts`. Bun runs it as
    * the load filter on the absolute path, so it should not anchor at the start.
    */
   include?: RegExp;
@@ -25,7 +26,8 @@ type HotOptions = {
    * `node_modules/`, `web/`, `generated/`, `__tests__/` or `tests/`, and `.test`/`.spec` files.
    * Tested on the path relative to the game root with a leading `/` and `/` separators, also on
    * Windows: `/features/home/view.tsx`. A folder above the game root never excludes a file. A
-   * `generated/strings.<locale>.ts` file is never excluded: the generated strings swap.
+   * `generated/strings.<locale>.ts` and a `generated/strings.<feature>.<locale>.ts` file are never
+   * excluded: the generated strings swap.
    */
   exclude?: RegExp;
 };

package/dist/hot.mjs

@@ -10,7 +10,7 @@ import { readFile } from "node:fs/promises";
 * the keys watch names. A view module is a `.tsx` file, a `styles.ts`, a `view.ts`, an
 * `animations.ts`, an `effects.ts`, any `.ts` directly in a `styles/`, `motion/`, `effects/` or
 * `views/` folder, any `.ts` directly in `world/projections/` or `world/layout/`, or a generated
-* `generated/strings.<locale>.ts`. The stamp module `.moku/assets-stamp.ts` gets the footer too:
+* `generated/strings.<locale>.ts` or `generated/strings.<feature>.<locale>.ts`. The stamp module `.moku/assets-stamp.ts` gets the footer too:
 * its new exports say which asset files changed. A logic module never gets the footer
 * (`world/components/` and `world/systems/` included: they are registered at start, and
 * `.moku/main.ts` too), so its save reaches the root and the page reloads and restores its state. `moku-game dev` lists the
@@ -21,9 +21,12 @@ import { readFile } from "node:fs/promises";
 * The default modules that swap: the view files by name or by kind folder, and the stamp module.
 * Three literals joined, so each stays readable.
 */
-const DEFAULT_INCLUDE = new RegExp(`(${/\.tsx|\/styles\.ts|\/view\.ts|\/animations\.ts|\/effects\.ts|\/generated\/strings\.[\w-]+\.ts/.source}|${/\/(?:styles|motion|effects|views)\/[^/]+\.ts|\/world\/(?:projections|layout)\/[^/]+\.ts/.source}|${/\/\.moku\/assets-stamp\.ts/.source})$`);
-/** The generated strings of one locale, the one file under `generated/` that swaps. */
-const STRINGS = /\/generated\/strings\.[\w-]+\.ts$/;
+const DEFAULT_INCLUDE = new RegExp(`(${/\.tsx|\/styles\.ts|\/view\.ts|\/animations\.ts|\/effects\.ts|\/generated\/strings\.(?:[\w-]+\.)?[\w-]+\.ts/.source}|${/\/(?:styles|motion|effects|views)\/[^/]+\.ts|\/world\/(?:projections|layout)\/[^/]+\.ts/.source}|${/\/\.moku\/assets-stamp\.ts/.source})$`);
+/**
+* The generated strings of one locale, whole-game or of one sub-feature: the files under
+* `generated/` that swap.
+*/
+const STRINGS = /\/generated\/strings\.(?:[\w-]+\.)?[\w-]+\.ts$/;
 /** The default folders and test files that never hot swap. The outer group only scopes the `$`. */
 const DEFAULT_EXCLUDE = /(\/(node_modules|web|generated|__tests__|tests)\/|\.(test|spec)\.tsx?$)/;
 /**