@moku-labs/game 0.0.1 → 0.0.2

package/dist/assets.d.mts

@@ -0,0 +1,161 @@
+import { l as Manifest } from "./types-DWILGrPn.mjs";
+
+//#region src/plugins/assets/scan/cli.d.ts
+/**
+ * The part of the branded console the scanner writes through. A `BrandConsole` fits it, and a
+ * test passes a recorder instead.
+ */
+type ScanUi = {
+  /** Writes one neutral line. */info(message: string): void; /** Writes one warning line. */
+  warn(message: string): void; /** Writes one error line. */
+  error(message: string, cause?: unknown): void;
+};
+/** What one strings compile reports back. `CompileReport` of i18n has this shape. */
+type StringsReport = {
+  /** True when an output on disk differs from what the compile produced. */changed: boolean; /** Every locale a feature brought a file for, sorted. */
+  locales: readonly string[]; /** Every message key, sorted. */
+  keys: readonly string[]; /** One line per key a locale lacks. Nothing here stops a build. */
+  notes: readonly string[];
+};
+/**
+ * Compiles the feature strings of a root into a folder, or checks them in a check run.
+ * `compileStrings` of i18n fits it, and a test passes a stub instead.
+ */
+type StringsCompiler = (root: string, out: string, options: {
+  check: boolean;
+}) => Promise<StringsReport>;
+/**
+ * Runs the asset key scanner: walk the features, write the manifest and the key module, then
+ * compile the feature strings next to the key module, or check that all of it is current.
+ * Nothing here calls `process.exit`; the caller does.
+ *
+ * @param argv - The arguments after the script name.
+ * @param compile - The strings compiler, `compileStrings` of i18n.
+ * @param ui - Where the lines go. The branded console by default.
+ * @returns The exit code: `1` when the scan or the compile failed or `--check` found a difference, else `0`.
+ * @example
+ * ```ts
+ * await runCli(["--root", "src", "--manifest", "public/assets/manifest.json", "--check"], compileStrings);
+ * // 1 when public/assets/manifest.json is older than the files in src/features
+ * ```
+ */
+declare function runCli(argv: string[], compile: StringsCompiler, ui?: ScanUi): Promise<number>;
+//#endregion
+//#region src/plugins/i18n/compile/compile.d.ts
+/**
+ * What one compile produced.
+ */
+type CompileReport = {
+  /** True when an output on disk differs from what the compile produced. */changed: boolean; /** Every locale a feature brought a file for, sorted. */
+  locales: readonly string[]; /** Every message key, sorted. */
+  keys: readonly string[]; /** One line per key a locale lacks. Nothing here stops a build. */
+  notes: readonly string[];
+};
+/**
+ * What one compile is told beyond its two paths.
+ */
+type CompileOptions = {
+  /** True for a check run: nothing is written. */check?: boolean; /** Name of the folder that holds the features. Default `"features"`. */
+  features?: string;
+};
+/**
+ * Walks `features/*​/strings/<locale>.json` of a game, compiles every message and writes the
+ * generated modules: the types module `strings.ts` and one `strings.<locale>.ts` per locale. A
+ * check run writes nothing and only reports whether something would change.
+ *
+ * @param root - Game source root, the folder that holds the features.
+ * @param out - The generated directory the modules are written into.
+ * @param options - Whether this is a check run, and what the features folder is called.
+ * @returns Whether an output differed, the locales, the keys and the notes.
+ * @throws {Error} One error that lists every problem the compile found.
+ * @example
+ * ```ts
+ * const report = await compileStrings("src", "src/generated");
+ * // report.locales: ["en", "ru"], report.changed: true on the first run
+ * ```
+ */
+declare function compileStrings(root: string, out: string, options?: CompileOptions): Promise<CompileReport>;
+/**
+ * Tells whether the generated modules of a game are current, without writing anything. The
+ * `--check` run of `bun run assets:keys` covers the strings with it.
+ *
+ * @param root - Game source root, the folder that holds the features.
+ * @param out - The generated directory the modules live in.
+ * @returns True when nothing would change.
+ * @throws {Error} One error that lists every problem the compile found.
+ * @example
+ * ```ts
+ * await checkStrings("src", "src/generated"); // false when a message changed since the last run
+ * ```
+ */
+declare function checkStrings(root: string, out: string): Promise<boolean>;
+//#endregion
+//#region src/plugins/assets/scan/emit.d.ts
+/**
+ * Writes `manifest.json`: two-space JSON with a trailing newline, bundles sorted by name and
+ * files sorted by key.
+ *
+ * @param manifest - What the scan produced.
+ * @returns The text of the file.
+ * @example
+ * ```ts
+ * emitManifest({ version: 1, bundles: {} }); // '{\n  "version": 1,\n  "bundles": {}\n}\n'
+ * ```
+ */
+declare function emitManifest(manifest: Manifest): string;
+/**
+ * Writes `generated/assets.ts`: `AssetKey` over every kind, the narrower `FontKey` and `AudioKey`
+ * next to it, `BundleKey`, and the nine-slice table. A game commits this file, so `defineGame` can
+ * type `Sprite`, a text style, a sound, `defineBundles` and the `load` effect from it.
+ *
+ * @param manifest - What the scan produced.
+ * @returns The text of the module.
+ * @example
+ * ```ts
+ * emitKeys({ version: 1, bundles: {} });
+ * // the header, four unions that are all "never" and an empty nine-slice table
+ * ```
+ */
+declare function emitKeys(manifest: Manifest): string;
+//#endregion
+//#region src/plugins/assets/scan/scan.d.ts
+/**
+ * What one scan is told: where the features are and where the two generated files go.
+ */
+type ScanOptions = {
+  /** Path of the game source root, the folder that holds the features. */root: string; /** Name of the folder that holds the features. Default `"features"`. */
+  features?: string; /** Path of the `manifest.json` to write. */
+  manifest: string; /** Path of the generated key module to write. */
+  keys: string; /** False for a check run: nothing is written. Default true. */
+  write?: boolean;
+};
+/**
+ * What a scan produced.
+ */
+type ScanResult = {
+  /** The manifest, with bundles sorted by name and files sorted by key. */manifest: Manifest; /** The text of the generated key module. */
+  keysSource: string; /** True when an output on disk differs from what the scan produced. */
+  changed: boolean; /** One line per file the scan left out. Nothing here stops a build. */
+  notes: readonly string[];
+};
+/**
+ * Walks the features of a game and writes its two generated files: one bundle per feature, split
+ * by the optional `assets.ts` of that feature, every file keyed by the key rule. A check run
+ * (`write: false`) writes nothing and only reports whether something would change.
+ *
+ * @param options - The game source root, the two output paths and whether to write.
+ * @returns The manifest, the text of the key module and whether an output differed.
+ * @throws {Error} One error that lists every problem the scan found.
+ * @example
+ * ```ts
+ * const { manifest, changed } = await scanAssets({
+ *   root: "src",
+ *   manifest: "public/assets/manifest.json",
+ *   keys: "src/generated/assets.ts"
+ * });
+ * // manifest.bundles.ui.files[0].key: "ui.button.primary", changed: true on the first run
+ * ```
+ */
+declare function scanAssets(options: ScanOptions): Promise<ScanResult>;
+//#endregion
+export { type CompileOptions, type CompileReport, type ScanOptions, type ScanResult, type ScanUi, type StringsCompiler, type StringsReport, checkStrings, compileStrings, emitKeys, emitManifest, runCli, scanAssets };