@datamoc/mw_games 0.44.2 → 0.45.0

package/tools/bundle-size.mjs

@@ -1,142 +1 @@
-#!/usr/bin/env node
-import { gzipSync } from 'node:zlib';
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
-import { join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-/**
- * The bundle-size budget: the rendering-backend policy weighs bundle cost, and this is the
- * number it weighs. Here it records the classic global build (the one file a script-tag player
- * downloads, raw and gzipped) and the whole published `dist` tree, source maps excluded so
- * the separate map-files decision cannot perturb it.
- *
- * `npm run size:check` fails when either grows past `MWG_SIZE_TOLERANCE` (default 2%) over
- * the committed baseline; `npm run size:update` rewrites the baseline after a deliberate
- * growth, the same "commit the new number on purpose" shape `npm run api:report` uses.
- * Run `npm run build` first.
- *
- * A game uses the same gate on its own build (item 386): `mwg-size dist` measures every file a
- * player receives, raw and gzipped, plus their total, against `size-budget.json` beside the
- * project (`--baseline=` to move it, `--update` to write it on purpose). A page that grows past
- * the tolerance fails the game's CI, which matters most for a player on a phone.
- */
-
-/** every file under `dir`, recursively */
-function walk(dir) {
-	const out = [];
-	for (const entry of readdirSync(dir, { withFileTypes: true })) {
-		const full = join(dir, entry.name);
-		if (entry.isDirectory()) out.push(...walk(full));
-		else out.push(full);
-	}
-	return out;
-}
-
-/**
- * Raw and gzipped bytes of every file a player receives from a finished build, keyed by path,
- * plus `total`. Source maps, precompressed siblings and SBOMs are left out: none of them is
- * what the page loads.
- */
-export function measureBuild(dist) {
-	const current = {};
-	let raw = 0;
-	let gzip = 0;
-	for (const file of walk(dist).sort()) {
-		const path = relative(dist, file).split(sep).join('/');
-		if (/\.(map|gz|br|xz)$/.test(path) || path.endsWith('.cdx.json')) continue;
-		const bytes = readFileSync(file);
-		const entry = { raw: bytes.length, gzip: gzipSync(bytes).length };
-		current[path] = entry;
-		raw += entry.raw;
-		gzip += entry.gzip;
-	}
-	current.total = { raw, gzip };
-	return current;
-}
-
-/**
- * Compares `current` with `baseline` metric by metric: a metric more than `tolerance` over its
- * baseline fails, one with no baseline (a new file) is reported and passes, since the total
- * still counts it. Returns the report lines and whether anything is over.
- */
-export function compareBudget(current, baseline, tolerance = 0.02) {
-	const lines = [];
-	let failed = false;
-	for (const [name, metrics] of Object.entries(current)) {
-		for (const [metric, bytes] of Object.entries(metrics)) {
-			const before = baseline[name]?.[metric];
-			if (before === undefined) {
-				lines.push(`${name} ${metric}: ${bytes} B (no baseline)`);
-				continue;
-			}
-			const growth = bytes / before - 1;
-			const over = growth > tolerance;
-			if (over) failed = true;
-			lines.push(
-				`${name} ${metric}: ${bytes} B vs ${before} B baseline (${growth >= 0 ? '+' : ''}${(growth * 100).toFixed(1)}%) ${over ? 'OVER' : 'ok'}`,
-			);
-		}
-	}
-	return { lines, failed };
-}
-
-/** this repository's own budget: the global bundle and the published `dist` tree */
-function measureFramework(root) {
-	const dist = join(root, 'dist');
-	const globalBundle = join(dist, 'mw_games.global.js');
-	if (!existsSync(globalBundle)) {
-		throw new Error(`no build found at ${relative(root, globalBundle)} - run "npm run build" first`);
-	}
-	const globalBytes = readFileSync(globalBundle);
-	return {
-		'mw_games.global.js': { raw: globalBytes.length, gzip: gzipSync(globalBytes).length },
-		dist: {
-			raw: walk(dist)
-				.filter((file) => !file.endsWith('.map'))
-				.reduce((sum, file) => sum + statSync(file).size, 0),
-		},
-	};
-}
-
-function main(argv) {
-	if (argv.includes('--help') || argv.includes('-h')) {
-		console.log('usage: mwg-size <dist folder> [--baseline=<file>] [--tolerance=0.02] [--update]');
-		return;
-	}
-	const tolerance = Number(
-		argv.find((a) => a.startsWith('--tolerance='))?.slice(12) ?? process.env.MWG_SIZE_TOLERANCE ?? 0.02,
-	);
-	const target = argv.find((arg) => !arg.startsWith('--'));
-	const root = resolve(import.meta.dirname, '..');
-	let current;
-	let baselinePath;
-	if (target) {
-		const dist = resolve(target);
-		if (!existsSync(join(dist, 'index.html')))
-			throw new Error(`${target} holds no index.html - build the game first`);
-		current = measureBuild(dist);
-		baselinePath = resolve(argv.find((a) => a.startsWith('--baseline='))?.slice(11) ?? 'size-budget.json');
-	} else {
-		current = measureFramework(root);
-		baselinePath = join(import.meta.dirname, 'bundle-size.json');
-	}
-	const update = target ? 'mwg-size --update' : 'npm run size:update';
-
-	if (argv.includes('--update') || (target && !existsSync(baselinePath))) {
-		writeFileSync(baselinePath, `${JSON.stringify(current, null, '\t')}\n`);
-		console.log(`wrote ${relative(process.cwd(), baselinePath)}`);
-		for (const [name, metrics] of Object.entries(current)) console.log(`  ${name}: ${JSON.stringify(metrics)}`);
-		return;
-	}
-	const { lines, failed } = compareBudget(current, JSON.parse(readFileSync(baselinePath, 'utf8')), tolerance);
-	for (const line of lines) console.log(line);
-	if (failed) {
-		console.error(
-			`bundle grew more than ${(tolerance * 100).toFixed(0)}% - trim it, or run "${update}" and explain the growth in the commit`,
-		);
-		process.exitCode = 1;
-	}
-}
-
-//realpath, since an npm `bin` shim reaches this file through a symlink
-if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
+export * from '@datamoc/mwg/tools/bundle-size';

package/tools/classic-html.d.mts

@@ -1,6 +1 @@
-export interface ClassicScriptResult {
-	html: string;
-	src: string;
-}
-
-export function toClassicScript(html: string): ClassicScriptResult | null;
+export * from '@datamoc/mwg/tools/classic-html';

package/tools/classic-html.mjs

@@ -1,69 +1 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-/**
- * Rewrites a bundler build's ES-module entry tag to a classic deferred script - the one HTML
- * edit every bundler-based game needs to open its own build by double-clicking, which is why
- * this is shipped rather than left for each game to reinvent (item 306).
- *
- * `type="module"` (and the `crossorigin` a bundler adds alongside it) both stop a `file://`
- * page from running the script; `defer` replaces the deferred-by-default behaviour a module
- * tag had, since a classic script is not deferred on its own and running from `<head>` before
- * `<body>` exists leaves a game with no canvas to attach to. The bundle itself must already be
- * a classic script (an IIFE or UMD build, not further ES module output) - this only touches
- * the tag pointing at it, the same split `mwg`'s own `vite.lib.config.ts` keeps between the
- * library's ES build and its `mwg.global.js` IIFE.
- *
- * Returns `null`, rather than guessing, when `html` carries no such tag - an unbuilt dev
- * template (Vite serves `/src/main.ts` directly, with no `crossorigin`, before a real build
- * emits a hashed asset path) is the case this guards a caller against silently "succeeding" on
- * the wrong file.
- *
- * @example
- * ```js
- * import { readFile, writeFile } from 'node:fs/promises';
- * import { toClassicScript } from '@datamoc/mw_games/tools/classic-html';
- *
- * const html = await readFile('dist/index.html', 'utf8');
- * const result = toClassicScript(html);
- * if (result) await writeFile('dist/index.html', result.html, 'utf8');
- * ```
- */
-export function toClassicScript(html) {
-	const scriptTag = /[ \t]*<script\b(?=[^>]*\btype="module")[^>]*\bsrc="([^"]+)"[^>]*><\/script>/;
-	const match = scriptTag.exec(html);
-	if (!match) return null;
-	return { html: html.replace(scriptTag, `<script defer src="${match[1]}"></script>`), src: match[1] };
-}
-
-async function runCli() {
-	const input = process.argv[2];
-	if (!input) {
-		console.error('Usage: node tools/classic-html.mjs dist/index.html');
-		process.exitCode = 2;
-	} else {
-		const path = resolve(input);
-		const html = await readFile(path, 'utf8');
-		const result = toClassicScript(html);
-		if (!result) {
-			console.error(
-				`${input}: no <script type="module" src="..."> entry tag found - is this a built page, ` +
-					'not the unbuilt dev template? (a dev template serves its source path directly, ' +
-					'with no bundled, hashed asset name yet)',
-			);
-			process.exitCode = 1;
-		} else {
-			await writeFile(path, result.html, 'utf8');
-			console.log(`${input}: rewrote the ${result.src} entry tag to a classic deferred script`);
-		}
-	}
-}
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-	//no top-level await: a vite config loaded as CommonJS has to be able to require() this module
-	runCli().catch((error) => {
-		console.error(error);
-		process.exitCode = 1;
-	});
-}
+export * from '@datamoc/mwg/tools/classic-html';

package/tools/compile-openings.d.mts

@@ -1,20 +1 @@
-import type { OpeningBook } from '../src/board/openings.ts';
-
-/** SAN tokens of one PGN line, without move numbers or results. */
-export function sanTokens(pgn: string): string[];
-
-/**
- * Resolves one SAN token against the position into a UCI move (`e2e4`, `e7e8q`).
- * Anything resolving to zero (or several) legal moves throws with the row it came
- * from, because a silent guess would poison every position past it.
- */
-export function sanToUci(state: import('../src/board/chess.ts').ChessState, san: string, context: string): string;
-
-/** A whole PGN line to UCI, played from the starting position. */
-export function lineToUci(pgn: string, context: string): string[];
-
-/**
- * Compiles every TSV row in `dir` into a book: each position along each line keeps the
- * continuation there, and the longest line through the position names it.
- */
-export function compileBook(dir: string): OpeningBook;
+export * from '@datamoc/mwg/tools/compile-openings';

package/tools/compile-openings.mjs

@@ -1,138 +1 @@
-#!/usr/bin/env node
-import { realpathSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
-import { join, relative } from 'node:path';
-//the framework's own modules: the TypeScript sources inside this repository, the built `dist` inside an
-//installed package, which ships no `src`
-const fromSource = existsSync(new URL('../src/board/chess.ts', import.meta.url));
-const load = (path) => import(fromSource ? `../src/${path}.ts` : `../dist/${path}.js`);
-const { applyMove, legalMoves, positionKey, sq, squareName, startingChess } = await load('board/chess');
-const { parseUciMove } = await load('board/openings');
-
-/**
- * Compiles opening tables (`eco`, `name`, `pgn` TSV rows, one per line after the header)
- * into a position-keyed book a game checks in beside its own code.
- *
- * Each row's PGN is SAN, resolved against the real move generator and replayed from the
- * starting position; every position along the line records the continuation, and the
- * longest line ending at a position names it (first seen wins ties). The output is plain
- * JSON (`{ version: 1, positions: { [key]: { eco?, name?, moves: [uci...] } } }`), keyed
- * by `positionKey`, which is what `board.probeBook` reads back.
- *
- * Only Node built-ins plus the framework's own board rules are used, so this adds no
- * dependency. Rows are vendored data (`data/openings/`, CC0), never fetched: re-vendoring
- * is copying five files at a new commit, and a row that no longer parses fails the
- * compile instead of silently dropping a line.
- *
- * usage: node tools/compile-openings.mjs <tsv folder> <book.json>
- */
-
-const PROMOTION_KIND = { q: 'queen', r: 'rook', b: 'bishop', n: 'knight' };
-const PROMOTION_LETTER = { queen: 'q', rook: 'r', bishop: 'b', knight: 'n' };
-
-/** SAN tokens of one PGN line, without move numbers or results */
-export function sanTokens(pgn) {
-	return pgn
-		.split(/\s+/)
-		.map((token) => token.replace(/^\d+\.+/, ''))
-		.filter((token) => token && !/^(1-0|0-1|1\/2-1\/2|\*)$/.test(token));
-}
-
-/**
- * Resolves one SAN token against the position into a UCI move (`e2e4`, `e7e8q`).
- * Castling, disambiguation, captures, promotions and trailing check/mate marks are
- * understood; anything resolving to zero (or several) legal moves throws with the row
- * it came from, because a silent guess would poison every position past it.
- */
-export function sanToUci(state, san, context) {
-	const move = san.replace(/[+#?!]+$/, '');
-	if (/^O-O(-O)?$/.test(move)) {
-		const home = state.turn === 'white' ? 0 : 56;
-		return squareName(home + 4) + squareName(home + (move === 'O-O' ? 6 : 2));
-	}
-	const match = /^([KQRBN]?)([a-h]?[1-8]?)(x?)([a-h][1-8])(?:=([QRBN]))?$/.exec(move);
-	if (!match) throw new Error(`${context}: cannot parse '${san}'`);
-	const kind = match[1] === '' ? 'pawn' : { K: 'king', Q: 'queen', R: 'rook', B: 'bishop', N: 'knight' }[match[1]];
-	const to = sq(match[4]);
-	const promotion = match[5] ? PROMOTION_KIND[match[5].toLowerCase()] : undefined;
-	const candidates = legalMoves(state).filter(
-		(candidate) =>
-			state.board[candidate.from]?.kind === kind &&
-			candidate.to === to &&
-			(candidate.promotion ?? null) === (promotion ?? null) &&
-			[...match[2]].every((c) => squareName(candidate.from).includes(c)),
-	);
-	if (candidates.length !== 1) throw new Error(`${context}: '${san}' matches ${candidates.length} moves`);
-	const chosen = candidates[0];
-	return (
-		squareName(chosen.from) + squareName(chosen.to) + (chosen.promotion ? PROMOTION_LETTER[chosen.promotion] : '')
-	);
-}
-
-/** a whole PGN line to UCI, played from the starting position */
-export function lineToUci(pgn, context) {
-	const state = startingChess();
-	const uci = [];
-	for (const san of sanTokens(pgn)) {
-		const move = sanToUci(state, san, context);
-		uci.push(move);
-		applyMove(state, parseUciMove(move));
-	}
-	return uci;
-}
-
-/**
- * Compiles every TSV row in `dir` into a book: each position along each line keeps the
- * continuation there, and the longest line ending at a position names it. Terminal
- * positions keep entries of their own, so a line that stops early still classifies.
- */
-export function compileBook(dir) {
-	const positions = {};
-	for (const file of readdirSync(dir)
-		.filter((entry) => entry.endsWith('.tsv'))
-		.sort()) {
-		const rows = readFileSync(join(dir, file), 'utf8').split('\n');
-		rows.slice(1).forEach((row, index) => {
-			if (!row.trim()) return;
-			const [eco, name, pgn] = row.split('\t');
-			const context = `${file}:${index + 2} (${eco} ${name})`;
-			if (!eco || !name || !pgn) throw new Error(`${context}: malformed row`);
-			const uci = lineToUci(pgn, context);
-			const state = startingChess();
-			const keys = [positionKey(state)];
-			for (const move of uci) {
-				applyMove(state, parseUciMove(move));
-				keys.push(positionKey(state));
-			}
-			keys.forEach((key, ply) => {
-				let entry = positions[key];
-				if (!entry) entry = positions[key] = { length: 0, moves: [] };
-				if (ply === uci.length && uci.length > entry.length) {
-					entry.eco = eco;
-					entry.name = name;
-					entry.length = uci.length;
-				}
-				if (ply < uci.length && !entry.moves.includes(uci[ply])) entry.moves.push(uci[ply]);
-			});
-		});
-	}
-	for (const key of Object.keys(positions)) delete positions[key].length;
-	return { version: 1, positions };
-}
-
-//the real path, since an npm `bin` shim reaches this file through a symlink; a suffix test on the
-//name is not enough (`compress-dist.mjs` ends with `t.mjs`)
-const isMain = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
-
-if (isMain) {
-	const [dir, out] = process.argv.slice(2);
-	if (!dir || !out) {
-		console.error('usage: node tools/compile-openings.mjs <tsv folder> <book.json>');
-		process.exit(1);
-	}
-	const book = compileBook(dir);
-	writeFileSync(out, `${JSON.stringify(book)}\n`);
-	const count = Object.keys(book.positions).length;
-	console.log(`  ${count} positions from ${relative(process.cwd(), dir)} -> ${relative(process.cwd(), out)}`);
-}
+export * from '@datamoc/mwg/tools/compile-openings';

package/tools/compile-resources.d.mts

@@ -1,66 +1 @@
-export const DEFAULT_MIME: Record<string, string>;
-
-export function walk(dir: string): AsyncGenerator<string>;
-
-export interface CompileResourcesOptions {
-	from: string;
-	to: string;
-	mime?: Record<string, string>;
-	groupBy?: (key: string) => string;
-	/** Exact paths relative to the asset folder to embed. Omit to include all; [] includes none. Unknown entries fail by name. */
-	assetFiles?: readonly string[];
-	toWebp?: boolean;
-	webpLossless?: boolean;
-	webpQuality?: number;
-	/** minify embedded `.svg` assets through the optional `svgo` package (version 4 or newer); false by default */
-	svgo?: boolean;
-	/** Subset an embedded `.sf2` to the programs the embedded `.mid`/`.midi` files use. Default true; `false` embeds every SoundFont whole. */
-	soundFont?: boolean;
-	/** Explicit `{ bank, program }` list to subset a SoundFont to, overriding the MIDI-derived list. */
-	soundFontUsage?: readonly SoundFontUsage[];
-}
-
-export interface CompileResourcesGroup {
-	name: string;
-	count: number;
-	size: number;
-}
-
-export interface CompileResourcesResult {
-	groups: CompileResourcesGroup[];
-	/** the asset path of every embedded file, as game code passes it to `load()` */
-	keys: string[];
-	rawBytes: number;
-	embeddedBytes: number;
-	webpConverted: number;
-	/** SVG assets embedded smaller than their source because of `svgo` */
-	svgOptimised: number;
-	skipped: number;
-	/** the `CREDITS.txt` text when the asset folder holds a `credits.json`, else null */
-	credits: string | null;
-	/** one entry per embedded `.sf2`: the programs kept (null when embedded whole) and the byte saving */
-	soundFonts: SoundFontEmbed[];
-}
-
-/** the plain-text credits for a manifest (an array, or `{ credits: [...] }`, of `{ name, license, author?, url? }`) */
-export function creditsText(manifest: unknown): string;
-
-export interface SoundFontUsage {
-	bank: number;
-	program: number;
-}
-
-export interface SoundFontEmbed {
-	key: string;
-	/** programs kept, or null when the font was embedded whole for lack of a usage list */
-	programs: number | null;
-	rawBytes: number;
-	embeddedBytes: number;
-	/** the programs the game's MIDI files ask for that this font does not carry; empty when none */
-	missing: SoundFontUsage[];
-}
-
-/** parses a `--soundfont-usage=bank:program,...` CLI value; undefined when the flag is absent */
-export function soundFontUsageFromFlag(value: string | undefined): SoundFontUsage[] | undefined;
-
-export function compileResources(options: CompileResourcesOptions): Promise<CompileResourcesResult>;
+export * from '@datamoc/mwg/tools/compile-resources';