@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/verify.js

@@ -0,0 +1,293 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { gateVerdicts } from "../verify/judge.js";
+import { normaliseCheck } from "../verify/probe.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { plannedFonts, rendererNote } from "../verify/health.js";
+import { serveDir } from "../verify/serve.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { criteriaOf } from "../criteria.js";
+import { REQUESTS } from "../smoke/orphans.js";
+import { consoleNote, consoleWitness } from "../verify/console.js";
+import { chromeFallbackNote, engine, viewportsFor } from "../verify/browser.js";
+import { browserPool, runUrl } from "../verify/run.js";
+import { launch } from "../verify/browser.js";
+import { rendererLine, timingVoid } from "../verify/gpu.js";
+import { playersVerdict, twoPlayers } from "../verify/players.js";
+import { handleBridge, PLAY_PATH } from "../relay/bridge.js";
+import { devGameId, startRelay } from "../relay/local.js";
+import { ui, verdictWord } from "../ui.js";
+import { isWorldGame, worldRead } from "../pipeline/pipeline.js";
+import { patchBoard } from "../status/board.js";
+const T_CHECK = 'npx @funpixel/tools check';
+export const EXIT = { pass: 0, fail: 1, not_observed: 2, error: 3 };
+async function readManifest(path) {
+    if (!path || !existsSync(path))
+        return {};
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function servedRoot(dir) {
+    if (existsSync(join(dir, 'dist', 'index.html')))
+        return join(dir, 'dist');
+    if (!existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'index.html')))
+        return dir;
+    return null;
+}
+export async function verify(opts, io = console) {
+    if (opts.players === 2)
+        return verifyPlayers(opts, io);
+    if (!opts.watch) {
+        const pool = browserPool();
+        try {
+            return await verifyOnce(opts, io, pool);
+        }
+        finally {
+            await pool.close();
+        }
+    }
+    return watch(opts, io);
+}
+async function watch(opts, io) {
+    const { watch: fsWatch } = await import('node:fs');
+    const { spawnSync } = await import('node:child_process');
+    const dir = resolve(opts.target ?? '.');
+    const pool = browserPool();
+    const u = ui(io, 'verify');
+    let pending, running = false, again = false;
+    const run = async () => {
+        if (running) {
+            again = true;
+            return;
+        }
+        running = true;
+        const vite = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'vite.cmd' : 'vite');
+        const built = spawnSync(vite, ['build', '--logLevel', 'error'], { cwd: dir, stdio: 'inherit', shell: process.platform === 'win32' });
+        if (built.status !== 0)
+            u.item('fail', 'build', 'waiting for the next change');
+        else
+            await verifyOnce({ ...opts, sweep: false }, io, pool);
+        running = false;
+        if (again) {
+            again = false;
+            await run();
+        }
+    };
+    const ignore = /(^|[\\/])(node_modules|dist|\.git|\.vite|\.funtools)([\\/]|$)|verify\.json$/;
+    fsWatch(dir, { recursive: true }, (_event, file) => {
+        if (!file || ignore.test(String(file)))
+            return;
+        clearTimeout(pending);
+        pending = setTimeout(run, 300);
+    });
+    u.heading(`verify --watch · ${dir}`);
+    u.line('every change rebuilds and re-verifies (Ctrl-C to stop)');
+    await run();
+    await new Promise((done) => process.once('SIGINT', () => done()));
+    await pool.close();
+    return EXIT.pass;
+}
+async function verifyOnce(opts, io, pool) {
+    const target = opts.target ?? '.';
+    const isUrl = /^https?:\/\//.test(target);
+    const dir = isUrl ? null : resolve(target);
+    let served = null;
+    let url = target;
+    if (dir) {
+        const root = servedRoot(dir);
+        if (!root) {
+            ui(io, 'verify').error(`no dist/index.html in ${dir}`, 'build the game first (npm run build)');
+            return EXIT.error;
+        }
+        served = await serveDir(root);
+        url = served.url;
+    }
+    const manifest = await readManifest(opts.manifest ?? (dir && join(dir, 'funpixel.json')));
+    const rawChecks = opts.checks ? JSON.parse(await readFile(opts.checks, 'utf8')) : manifest.checks;
+    const checks = (Array.isArray(rawChecks) ? rawChecks : []).map(normaliseCheck);
+    const { criteria } = criteriaOf(manifest);
+    const fetched = new Set();
+    const origin = served ? new URL(served.url).origin : null;
+    const witness = consoleWitness();
+    try {
+        const { verdict, runs } = await runUrl(pool, url, {
+            onPage: (page) => {
+                witness.attach(page);
+                page.on('request', (r) => {
+                    try {
+                        const u = new URL(r.url());
+                        if (u.origin === origin)
+                            fetched.add(decodeURIComponent(u.pathname).replace(/^\/+/, ''));
+                    }
+                    catch { }
+                });
+            },
+            checks,
+            sweepMs: opts.sweep ? 3000 : 0,
+            viewports: viewportsFor(opts.viewport ?? 'desktop'),
+            orientation: typeof manifest.metadata?.orientation === 'string' ? manifest.metadata.orientation : '',
+            hooks: hookMapOf(manifest),
+            fonts: plannedFonts(manifest),
+            frontDoor: opts.frontDoor ?? null,
+        });
+        const first = runs[0];
+        const console_errors = witness.errors();
+        if (opts.report) {
+            io.log(JSON.stringify(first.report, null, 2));
+        }
+        else if (opts.json) {
+            io.log(JSON.stringify({ verdict, gates: gateVerdicts(first.report), report: first.report, viewports: runs.map(runSummary), console_errors }, null, 2));
+        }
+        else {
+            printSummary(ui(io, 'verify'), dir ?? target, verdict, runs, pool.usedChrome(), criteria.length, console_errors);
+        }
+        if (dir) {
+            await mkdir(join(dir, '.funtools', 'verify'), { recursive: true });
+            await writeFile(join(dir, REQUESTS), JSON.stringify({ at: new Date().toISOString(), paths: [...fetched].filter(Boolean).sort() }, null, 2) + '\n');
+            const fp = await fingerprint(dir);
+            const webkit = engine() === 'webkit';
+            if (webkit && !opts.json && !opts.report)
+                ui(io, 'verify').item('note', `ran on Playwright's WebKit (Safari's engine, no Safari UI): recorded in ${WEBKIT_RECORD}; verify.json stays Chromium's, the engine the server's probe runs`);
+            await writeFile(join(dir, webkit ? WEBKIT_RECORD : 'verify.json'), JSON.stringify({
+                tool: 'funtools', version: 1, verdict, ...fp, ...(webkit ? { engine: 'webkit' } : {}), at: new Date().toISOString(),
+                viewports: runs.map(runSummary), report: first.report, ...(criteria.length ? { criteria } : {}),
+                ...(console_errors.count ? { console_errors } : {}),
+            }, null, 2) + '\n');
+            if (!webkit) {
+                const e = errorsPart(verdict, runs, console_errors);
+                if (e)
+                    patchBoard(dir, { errors: { verify: e } });
+            }
+            if (!opts.json && !opts.report && !webkit && isWorldGame(dir).world) {
+                const w = worldRead(dir, fp.fingerprint);
+                if (w.state !== 'met')
+                    ui(io, 'verify').item(w.state === 'failing' ? 'warn' : 'note', `world: ${w.says}`, `${T_CHECK} --world judges it (boxes, grounding, life); the slice gate and its card read it`);
+            }
+        }
+        return EXIT[verdict];
+    }
+    finally {
+        if (served)
+            await served.close();
+    }
+}
+export function errorsPart(verdict, runs, logged) {
+    const failing = new Map();
+    for (const r of runs)
+        for (const g of gateVerdicts(r.report))
+            if (!g.pass && !failing.has(g.what))
+                failing.set(g.what, g.reason);
+    const pages = logged.unique;
+    if (verdict === 'not_observed' && !failing.size && !pages.length)
+        return null;
+    const detail = [...[...failing].map(([what, why]) => `fault: ${what}${why ? ` — ${why.slice(0, 120)}` : ''}`), ...pages.map((l) => `page: ${l}`)];
+    return { value: failing.size + pages.length, by: 'verify', detail };
+}
+export const WEBKIT_RECORD = join('.funtools', 'verify', 'webkit.json');
+const runSummary = (r) => {
+    const timing_void = timingVoid(r.renderer, !!r.softwareGl);
+    return { viewport: r.viewport, verdict: r.verdict, renderer: r.renderer, ...(timing_void ? { timing_void } : {}), ...(r.softwareGl ? { software_gl: r.softwareGl } : {}) };
+};
+const STATUS = { pass: 'pass', fail: 'fail', not_observed: 'not_observed' };
+function notes(r) {
+    const out = [];
+    const h = r.render_health;
+    if (h && h.key_parity_observed && h.unreachable_keys.length)
+        out.push(['note', `keys with no touch route: ${h.unreachable_keys.join(', ')} — a swipe, drag or lift on the play that stands for them claims them: data-fpx-gesture="${h.unreachable_keys.map((k) => k.replace(/\(.*$/, '')).join(' ')}" on the play element (skill funpixel-mobile-ui)`]);
+    if (r.play?.kind === 'static')
+        out.push(['note', `nothing moved in two seconds, idle or pressing ${r.play.inputs} — fine for a board that waits for its own taps, a stuck screen otherwise`]);
+    if (r.play && !r.play.observed)
+        out.push(['not_observed', 'two seconds of play: the canvas could not be read back']);
+    if (r.levels?.note)
+        out.push(['note', r.levels.note]);
+    for (const l of r.levels?.levels ?? [])
+        if (l.status === 'not_observed')
+            out.push(['not_observed', `solve(${l.index}): ${l.error}`]);
+    for (const f of r.fonts?.fonts ?? []) {
+        if (f.status === 'system')
+            out.push(['not_observed', `the font "${f.family}" has no @font-face; it renders only where the device has it`]);
+        if (f.status === 'timeout')
+            out.push(['not_observed', `the font "${f.family}" did not finish loading in time`]);
+    }
+    for (const s of r.audio_files?.skipped ?? [])
+        if (!s.endsWith('not there)'))
+            out.push(['not_observed', `sound file ${s}`]);
+    const heavy = rendererNote(r.renderer);
+    if (heavy)
+        out.push(['note', heavy]);
+    const m = r.hook_map;
+    if (m?.unresolved.length)
+        out.push(['note', `funpixel.json hooks that read nothing: ${m.unresolved.join(', ')} — check the paths`]);
+    return out;
+}
+function printSummary(u, target, verdict, runs, chrome, criteria = 0, errors = { count: 0, unique: [] }) {
+    for (const run of runs) {
+        u.heading(`${run.viewport} · ${target}`);
+        if (!run.report.instrumented)
+            u.item('not_observed', 'hooks', 'the game declares no __FPX_STATE__/__FPX_VERBS__ (funtools doctor --add-hooks)');
+        if (run.softwareGl)
+            u.item('note', `re-ran on software GL (SwiftShader), as the hosted probe renders: ${run.softwareGl}`);
+        const timing = timingVoid(run.renderer, !!run.softwareGl);
+        u.item(timing ? 'not_observed' : 'note', timing ? `times VOID (the gates stand; sweep and wait times are not the game's) — ${timing}` : rendererLine(run.renderer, !!run.softwareGl));
+        for (const g of gateVerdicts(run.report))
+            u.item(g.pass ? 'pass' : 'fail', g.what, g.pass ? undefined : g.reason || undefined);
+        for (const n of notes(run.report))
+            u.item(n[0], n[1]);
+    }
+    const said = consoleNote(errors);
+    if (said)
+        u.item('note', said);
+    if (chrome)
+        u.item(...chromeFallbackNote());
+    if (criteria)
+        u.item('note', `${criteria} criteria recorded for the player agent and the panel (funtools play; judged from outside, not here)`);
+    const gates = runs.flatMap((r) => gateVerdicts(r.report));
+    const failed = gates.filter((g) => !g.pass).length;
+    const detail = runs.length > 1
+        ? runs.map((r) => `${r.viewport} ${verdictWord(r.verdict)}`).join(' · ')
+        : verdict === 'not_observed' ? 'nothing could be judged — never read as a pass'
+            : `${gates.length - failed} of ${gates.length} gate(s) passed`;
+    u.summary(STATUS[verdict], `${verdictWord(verdict)} — ${detail}`);
+}
+async function verifyPlayers(opts, io) {
+    const u = ui(io, 'verify');
+    const target = opts.target ?? '.';
+    if (/^https?:\/\//.test(target)) {
+        u.error('--players 2 needs the game folder, not a URL', 'run it in the game folder: the relay tickets are minted locally');
+        return EXIT.error;
+    }
+    const dir = resolve(target);
+    const root = servedRoot(dir);
+    if (!root) {
+        u.error(`no dist/index.html in ${dir}`, 'build the game first (npm run build)');
+        return EXIT.error;
+    }
+    const relay = await startRelay();
+    const gameId = devGameId(dir);
+    const served = await serveDir(root, (req, res) => handleBridge(req, res, relay.redisUrl, gameId));
+    const { browser } = await launch();
+    try {
+        const steps = await twoPlayers(browser, `${served.url.replace(/\/$/, '')}${PLAY_PATH}`);
+        const verdict = playersVerdict(steps);
+        if (opts.json)
+            io.log(JSON.stringify({ verdict, players: 2, room: `dev-${gameId}`, relay: relay.reused ? 'reused' : 'started', steps }, null, 2));
+        else {
+            u.heading(`two players · ${dir}`);
+            u.item('note', `${relay.reused ? 'the relay already on :7370' : 'a local relay on :7370'}, room dev-${gameId}`);
+            for (const s of steps)
+                u.item(s.verdict, s.what, s.reason || undefined);
+            u.summary(STATUS[verdict], `${verdictWord(verdict)}${verdict === 'not_observed' ? ' — never read as a pass' : ''}`);
+        }
+        return EXIT[verdict];
+    }
+    finally {
+        await browser.close();
+        await served.close();
+        await relay.stop();
+    }
+}