@moku-labs/game 0.7.1 → 0.9.0

package/dist/project.d.mts

@@ -4,8 +4,9 @@
  * 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, 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.
+ * holds a line number; `find` reads the line from the file as it is on disk at the call. Names are
+ * followed through relative imports and the tsconfig `paths` of the game. No type here names a
+ * `typescript` type, so the shipped declarations need no TypeScript.
  */
 /**
  * What `openProject` reads. Paths are root-relative POSIX; the root itself is resolved against the
@@ -13,13 +14,20 @@
  *
  * @example
  * ```ts
- * // The editor opens the fixture game with the default manifest and a slower debounce.
- * const options: ProjectOptions = { root: "tests/integration/merge-game", debounceMs: 120 };
+ * // The editor opens the mini game with the default manifest and a slower debounce.
+ * const options: ProjectOptions = { root: "tests/fixtures/mini-game", debounceMs: 120 };
+ * // A v15 game whose aliases live in a second tsconfig.
+ * const game: ProjectOptions = { root: "games/orders", tsconfig: "tsconfig.game.json" };
  * ```
  */
 type ProjectOptions = {
   /** The folder of the game. A path that is not a directory rejects `openProject`. */root: string; /** The asset manifest, root-relative. Default `manifest.json`, the scanner's default. */
-  manifest?: string; /** The quiet period, in milliseconds, that closes a batch of file events. Default 75. */
+  manifest?: string;
+  /**
+   * The tsconfig whose `paths` the index follows, root-relative. Default `tsconfig.json`. A path
+   * that leaves the root or a file that does not parse rejects `openProject`.
+   */
+  tsconfig?: string; /** The quiet period, in milliseconds, that closes a batch of file events. Default 75. */
   debounceMs?: number;
 };
 /**
@@ -29,7 +37,7 @@ type ProjectOptions = {
  *
  * @example
  * ```ts
- * const kind: JsxKind = "idProp"; // id="settingsBoard" on <Signboard>
+ * const kind: JsxKind = "idProp"; // id="infoPanel" on <Panel>
  * ```
  */
 type JsxKind = "literal" | "template" | "idProp" | "ident";
@@ -39,8 +47,8 @@ type JsxKind = "literal" | "template" | "idProp" | "ident";
  *
  * @example
  * ```ts
- * // node:board/merge, defined by the const `merge` of nodes/merge.ts.
- * const anchor: Anchor = { path: "nodes/merge.ts", binding: "merge" };
+ * // node:infoPopup/count, defined by the const `count` of nodes/count.ts.
+ * const anchor: Anchor = { path: "nodes/count.ts", binding: "count" };
  * ```
  */
 type Anchor = {
@@ -66,14 +74,17 @@ type Anchor = {
  *
  * @example
  * ```ts
- * index.symbols["flow:board"]; // { def: [{ path: "flows/board.ts", binding: "boardFlow" }] }
- * index.files["nodes/merge.ts"]?.state; // "ok"
+ * index.symbols["flow:infoPopup"]; // { def: [{ path: "flows/info.ts", binding: "infoFlow" }] }
+ * index.files["nodes/count.ts"]?.state; // "ok"
+ * // A game whose tsconfig.json holds paths, such as tests/fixtures/layout-game.
+ * index.tsconfig; // "tsconfig.json"
  * ```
  */
 type ProjectIndex = {
   /** The shape of this object. A change of shape bumps it. */schemaVersion: 1; /** sha1 hex over the sorted lines `${path}\0${hash}\n` of every indexed file. */
   revision: string; /** The asset manifest, root-relative, when that file exists. */
-  manifest?: string;
+  manifest?: string; /** The tsconfig, root-relative, when that file exists and holds `paths` the index follows. */
+  tsconfig?: string;
   /**
    * 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.
@@ -99,9 +110,9 @@ type ProjectIndex = {
  *
  * @example
  * ```ts
- * // An agent moved nodes/toast.ts to nodes/board/toast.ts and fixed the import of the board flow.
- * change.files; // ["flows/board.ts", "nodes/board/toast.ts", "nodes/toast.ts"]
- * change.moved; // [{ key: "node:board/toast", from: "nodes/toast.ts", to: "nodes/board/toast.ts" }]
+ * // An agent moved nodes/count.ts to nodes/info/count.ts and fixed the import of the info flow.
+ * change.files; // ["flows/info.ts", "nodes/count.ts", "nodes/info/count.ts"]
+ * change.moved; // [{ key: "node:infoPopup/count", from: "nodes/count.ts", to: "nodes/info/count.ts" }]
  * change.removed; // []
  * ```
  */
@@ -123,9 +134,9 @@ type ProjectChange = {
  *
  * @example
  * ```ts
- * // The editor opens the Home scene of the fixture game.
+ * // The editor opens the Home scene of the mini game.
  * const [found] = await project.find("scene:home");
- * [found?.path, found?.line, found?.range]; // ["features/home/scene.ts", 8, [8, 1, 13, 4]]
+ * [found?.path, found?.line, found?.range]; // ["features/home/scene.ts", 8, [8, 1, 12, 4]]
  * ```
  */
 type Found = Anchor & {
@@ -145,26 +156,27 @@ type ProjectApi = {
    * @example
    * ```ts
    * // The editor checks a node file before it opens it.
-   * project.index.files["nodes/merge.ts"]?.state; // "ok"
+   * project.index.files["nodes/count.ts"]?.state; // "ok"
    * ```
    */
   readonly index: ProjectIndex;
   /**
-   * 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}` 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 `[]`.
+   * Answers where a key is defined, with lines read from the file on disk now. A name is followed
+   * through relative imports and the tsconfig aliases, so `@features/home` reaches the file that
+   * declares the node. 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}`
+   * 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`.
+   * @param key - An engine id: `node:infoPopup/count`, `flow:main`, `textStyle:ui.counter`, `jsx:infoPanelSpark`.
    * @returns One entry per place, in the order above; `broken` when the file does not parse now.
    * @example
    * ```ts
-   * // 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:290"]
+   * // The editor jumps to the node the flow view clicked, and to the spark of the info panel.
+   * (await project.find("node:infoPopup/count"))[0]?.line; // 7, in "nodes/count.ts"
+   * (await project.find("jsx:infoPanelSpark")).map(found => `${found.path}:${found.line}`);
+   * // ["features/info/popup.tsx:65", "features/info/popup.tsx:79"]
    * ```
    */
   find(key: string): Promise<Found[]>;
@@ -190,17 +202,20 @@ type ProjectApi = {
   watch(onIndex: (index: ProjectIndex, change: ProjectChange) => void): () => void;
   /**
    * Re-indexes one root-relative path now, for a caller that watches files itself. A deleted
-   * file drops its entries; a path that is not a `.ts` or `.tsx` source of the index changes
-   * nothing. The watch callers are not called.
+   * file drops its entries. The tsconfig, or a file it extends, reads the aliases again, and the
+   * index is rebuilt when names now follow them elsewhere. Any other path that is not a `.ts` or
+   * `.tsx` source of the index changes nothing. The watch callers are not called.
    *
    * @param path - The root-relative POSIX path of the file.
    * @returns The index after the file was read.
    * @throws {Error} When the path leaves the root, by `..` or by a symlink.
    * @example
    * ```ts
-   * // The editor saved nodes/merge.ts through its own file layer.
-   * const index = await project.changed("nodes/merge.ts");
-   * index.files["nodes/merge.ts"]?.state; // "ok"
+   * // The editor saved nodes/count.ts through its own file layer.
+   * const index = await project.changed("nodes/count.ts");
+   * index.files["nodes/count.ts"]?.state; // "ok"
+   * // It added a paths block to tsconfig.json: the keys behind the aliases join the index.
+   * (await project.changed("tsconfig.json")).tsconfig; // "tsconfig.json"
    * ```
    */
   changed(path: string): Promise<ProjectIndex>;
@@ -247,9 +262,9 @@ type IndexUi = {
  *   `--check` that found a broken file or a conflict; else `0`.
  * @example
  * ```ts
- * // An agent asks where a node of the fixture game lives.
- * await runCli(["--root", "tests/integration/merge-game", "where", "node:board/merge"]);
- * // 0, and the console printed "nodes/merge.ts:17"
+ * // An agent asks where a node of the mini game lives.
+ * await runCli(["--root", "tests/fixtures/mini-game", "where", "node:infoPopup/count"]);
+ * // 0, and the console printed "nodes/count.ts:7"
  * ```
  */
 declare function runCli(argv: readonly string[], ui?: IndexUi): Promise<number>;
@@ -260,16 +275,17 @@ declare function runCli(argv: readonly string[], ui?: IndexUi): Promise<number>;
  * path), loads TypeScript, parses every source file and builds the index. Nothing is written to
  * disk and nothing is inferred from the working directory but the root itself.
  *
- * @param options - The game root, the manifest path and the quiet period of `watch`.
+ * @param options - The game root, the manifest path, the tsconfig whose `paths` the index follows
+ *   (`tsconfig`, root-relative, `tsconfig.json` by default) and the quiet period of `watch`.
  * @returns The handle; close it when the game closes.
  * @throws {Error} When the root is missing or not a directory, or the `typescript` package is not
  *   installed: `[game] The project index needs the "typescript" package.`
  * @example
  * ```ts
- * // The editor opens the fixture game and answers where a node and a text style live.
- * const project = await openProject({ root: "tests/integration/merge-game" });
- * Object.keys(project.index.files).length; // 111
- * (await project.find("textStyle:ui.title"))[0]?.line; // 39, in "features/ui/styles.ts"
+ * // The editor opens the mini game and answers where a node and a text style live.
+ * const project = await openProject({ root: "tests/fixtures/mini-game" });
+ * Object.keys(project.index.files).length; // 21
+ * (await project.find("textStyle:ui.counter"))[0]?.line; // 16, in "features/home/styles.ts"
  * project.close();
  * ```
  */