@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/spec/extract.js

@@ -0,0 +1,123 @@
+const NUM = String.raw `-?(?:\d[\d_]*\.?\d*|\.\d+)(?:e[-+]?\d+)?`;
+const SCALAR = new RegExp(String.raw `^(?<lead>.*?)export const (?<decls>[A-Z][A-Z0-9_]*\s*=\s*${NUM}(?:\s*,\s*[A-Z][A-Z0-9_]*\s*=\s*${NUM})*)\s*;\s*(?<tail>//.*)?$`);
+const TABLE_OPEN = /^(?<lead>\s*)export const (?<name>[A-Z][A-Z0-9_]*) = \{\s*$/;
+const TABLE_CLOSE = /^\s*\}(?:\s*as const)?\s*;\s*$/;
+const ENTRY = new RegExp(String.raw `(?<key>[A-Za-z_$][\w$]*)\s*:\s*(?<value>${NUM})\s*(?:,|$)`, 'g');
+export const parseNumber = (s) => Number(s.replace(/_/g, ''));
+const docText = (s) => s.replace(/\/\*\*|\*\//g, '').split('\n').map((l) => l.replace(/^\s*\*\s?/, '').trim()).join(' ').replace(/\s+/g, ' ').trim();
+const lower = (s) => s.toLowerCase();
+function docFor(lines, i, lead = '') {
+    const inline = /\/\*\*([\s\S]*?)\*\//.exec(lead);
+    if (inline)
+        return docText(inline[0]) || undefined;
+    let j = i - 1;
+    const block = [];
+    if (/\*\//.test(lead))
+        block.push(lead.slice(0, lead.lastIndexOf('*/') + 2));
+    else if (j < 0 || !/\*\/\s*$/.test(lines[j]))
+        return undefined;
+    for (; j >= 0; j--) {
+        block.unshift(lines[j]);
+        if (/\/\*\*/.test(lines[j]))
+            break;
+    }
+    return docText(block.join('\n')) || undefined;
+}
+const whyFor = (doc, name, alone) => (doc && (alone || new RegExp(`\\b${name}\\b`).test(doc)) ? doc : undefined);
+export function findNumbers(file, text, stem) {
+    const lines = text.split('\n'), out = [];
+    const scalars = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = SCALAR.exec(lines[i]);
+        if (m?.groups) {
+            const decls = m.groups.decls.split(/\s*,\s*/).map((d) => d.split(/\s*=\s*/));
+            const doc = docFor(lines, i, m.groups.lead);
+            for (const [name, v] of decls)
+                scalars.push({ line: i + 1, name, value: parseNumber(v), why: whyFor(doc, name, decls.length === 1) });
+            continue;
+        }
+        const t = TABLE_OPEN.exec(lines[i]);
+        if (t?.groups) {
+            const end = lines.findIndex((l, k) => k > i && TABLE_CLOSE.test(l));
+            if (end < 0)
+                continue;
+            const body = lines.slice(i + 1, end), entries = [];
+            let all = true, doc;
+            for (let k = 0; k < body.length; k++) {
+                const raw = body[k], code = raw.replace(/\/\*\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/, '').trim();
+                if (/^\/\*\*/.test(raw.trim())) {
+                    doc = docText(raw);
+                    continue;
+                }
+                if (!code)
+                    continue;
+                const found = [...code.matchAll(ENTRY)];
+                const rest = code.replace(ENTRY, '').replace(/[\s,]/g, '');
+                if (!found.length || rest) {
+                    all = false;
+                    break;
+                }
+                const tableName = lower(t.groups.name) === 'tune' ? stem : lower(t.groups.name);
+                for (const e of found)
+                    entries.push({ file, line: i + 2 + k, name: t.groups.name, prop: e.groups.key, value: parseNumber(e.groups.value), group: tableName, key: e.groups.key, ...(doc ? { why: doc } : {}) });
+            }
+            if (all && entries.length)
+                out.push(...entries);
+            i = end;
+        }
+    }
+    const first = (n) => n.split('_')[0];
+    const count = new Map();
+    for (const s of scalars)
+        if (s.name.includes('_'))
+            count.set(first(s.name), (count.get(first(s.name)) ?? 0) + 1);
+    for (const s of scalars) {
+        const grouped = s.name.includes('_') && (count.get(first(s.name)) ?? 0) >= 2;
+        out.push({ file, line: s.line, name: s.name, value: s.value, group: grouped ? lower(first(s.name)) : stem, key: grouped ? lower(s.name.slice(first(s.name).length + 1)) : lower(s.name), ...(s.why ? { why: s.why } : {}) });
+    }
+    return out.sort((a, b) => a.line - b.line);
+}
+export function settleIds(found) {
+    const seen = new Set();
+    return found.map((f) => {
+        let key = f.key;
+        if (seen.has(`${f.group}.${key}`) && !f.prop)
+            key = `${f.file.replace(/^.*\/|\.\w+$/g, '')}_${key}`;
+        seen.add(`${f.group}.${key}`);
+        return { ...f, key };
+    });
+}
+export function rewire(text, found, tuneImport = './tune') {
+    const lines = text.split('\n'), mine = (n) => found.filter((f) => f.line === n);
+    const out = [];
+    let used = false, scalar = false;
+    for (let i = 0; i < lines.length; i++) {
+        const m = SCALAR.exec(lines[i]);
+        const here = mine(i + 1).filter((f) => !f.prop);
+        if (m?.groups && here.length) {
+            const names = here.map((f) => `${f.name}: number`).join(', ');
+            const byGroup = new Map();
+            for (const f of here)
+                byGroup.set(f.group, [...(byGroup.get(f.group) ?? []), f]);
+            const reads = [...byGroup].map(([g, fs]) => `({ ${fs.map((f) => (f.key === f.name ? f.name : `${f.key}: ${f.name}`)).join(', ')} } = group('${g}'))`).join(', ');
+            out.push(`${m.groups.lead}export let ${names}; onTune(() => { ${reads}; });${m.groups.tail ? ` ${m.groups.tail}` : ''}`);
+            used = scalar = true;
+            continue;
+        }
+        const t = TABLE_OPEN.exec(lines[i]);
+        const entries = t?.groups ? found.filter((f) => f.prop && f.name === t.groups.name && f.line > i + 1) : [];
+        if (t?.groups && entries.length) {
+            const end = lines.findIndex((l, k) => k > i && TABLE_CLOSE.test(l));
+            out.push(`${t.groups.lead}export const ${t.groups.name} = group('${entries[0].group}');`);
+            i = end;
+            used = true;
+            continue;
+        }
+        out.push(lines[i]);
+    }
+    if (!used)
+        return text;
+    const at = out.findIndex((l) => l.trim() && !/^\s*\/\//.test(l));
+    out.splice(at < 0 ? 0 : at, 0, `import { ${scalar ? 'group, onTune' : 'group'} } from '${tuneImport}';`);
+    return out.join('\n');
+}

package/dist/spec/lint.js

@@ -0,0 +1,261 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { byId, readTunables, SPEC_DIR } from "./tunables.js";
+import { builtEarly, clock, END, readOpen, specRooms, uniqueRooms } from "./rooms.js";
+import { filesFor, sectionsFor } from "./sections.js";
+const read = (p) => { try {
+    return readFileSync(p, 'utf8');
+}
+catch {
+    return '';
+} };
+const list = (xs, n = 6) => `${xs.slice(0, n).join(', ')}${xs.length > n ? ` and ${xs.length - n} more` : ''}`;
+const FILE_EXT = /^(md|json|ts|tsx|js|mjs|html|css|png|jpe?g|webp|mp3|ogg|wav|glb|gltf|txt)$/i;
+const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+const code = (t) => t.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' ')).replace(/(^|[^:'"`])\/\/.*$/gm, '$1');
+export const proseWords = (md) => md.replace(/<!--[\s\S]*?-->/g, ' ').replace(/^#.*$/gm, ' ').replace(/^\s*\|?[\s:|-]+\|?\s*$/gm, ' ').replace(/```[\s\S]*?```/g, ' ').split(/\s+/).filter((w) => /[A-Za-z]{2,}/.test(w)).length;
+function walkFiles(root, rel, test, depth = 0, out = []) {
+    let names = [];
+    try {
+        names = readdirSync(join(root, rel)).sort();
+    }
+    catch {
+        return out;
+    }
+    for (const n of names) {
+        if (n === 'node_modules' || n.startsWith('.'))
+            continue;
+        const p = rel ? `${rel}/${n}` : n;
+        let st;
+        try {
+            st = statSync(join(root, p));
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            if (depth < 6)
+                walkFiles(root, p, test, depth + 1, out);
+        }
+        else if (test(n))
+            out.push(p);
+    }
+    return out;
+}
+export function lintSpec(o) {
+    const { root } = o, specDir = o.specDir ?? SPEC_DIR, srcDir = o.srcDir ?? 'src';
+    const f = [];
+    const add = (check, state, says, next) => f.push({ check, state, says, ...(next ? { next } : {}) });
+    const names = (() => { try {
+        return readdirSync(join(root, specDir));
+    }
+    catch {
+        return [];
+    } })();
+    const mdFiles = names.filter((n) => /\.md$/i.test(n));
+    const specText = mdFiles.map((n) => read(join(root, specDir, n))).join('\n');
+    if (!o.tier)
+        add('sections', 'not measured', 'no tier past small (funpixel.json production.tier): which sections are needed is not known', 'spec lint --tier mid|deep');
+    else {
+        const missing = [], thin = [];
+        for (const s of sectionsFor(o.tier)) {
+            const have = filesFor(s, names);
+            if (!have.length) {
+                missing.push(`${s.file} (${s.title.toLowerCase()})`);
+                continue;
+            }
+            const md = have.filter((n) => /\.md$/i.test(n));
+            if (md.length && md.every((n) => proseWords(read(join(root, specDir, n))) < 25))
+                thin.push(md[0]);
+        }
+        if (missing.length)
+            add('sections', 'warn', `the ${o.tier} tier needs ${missing.length} section${missing.length === 1 ? '' : 's'} not here: ${list(missing, 10)}`, 'funtools spec init writes the outline of each; or name the file you keep it in');
+        else
+            add('sections', 'ok', `every section the ${o.tier} tier needs is here (${sectionsFor(o.tier).length})`);
+        if (thin.length)
+            add('sections', 'note', `still the outline: ${list(thin)} (fewer than 25 words written)`, 'write them as the game grows: each is the brief for the lane that owns it');
+        const open = (specText.match(/<!--\s*write:/g) ?? []).length;
+        if (open)
+            add('sections', 'note', `${open} place${open === 1 ? '' : 's'} marked <!-- write: … --> still to write`);
+    }
+    const t = readTunables(root, specDir);
+    let table = [];
+    if ('missing' in t)
+        add('tunables', 'warn', `no ${t.rel}: every number the game uses lives there`, 'funtools spec init writes it from the numbers the code holds');
+    else if ('broken' in t)
+        add('tunables', 'warn', `${t.rel} is not JSON: ${t.broken}`);
+    else {
+        table = t.list;
+        for (const p of t.problems)
+            add('tunables', 'warn', `${t.rel}: ${p}`);
+        const seen = new Set(), dup = [], noDefault = [], outside = [], badType = [];
+        for (const x of table) {
+            if (seen.has(x.id))
+                dup.push(x.id);
+            seen.add(x.id);
+            if (x.default === undefined) {
+                noDefault.push(x.id);
+                continue;
+            }
+            if (x.range && typeof x.default === 'number' && (x.default < x.range[0] || x.default > x.range[1]))
+                outside.push(`${x.id} ${x.default} outside ${x.range[0]}–${x.range[1]}`);
+            if (x.type === 'int' && !(Number.isInteger(x.default)))
+                badType.push(`${x.id} is not a whole number`);
+            if ((x.type === 'bool' || x.type === 'boolean') && typeof x.default !== 'boolean')
+                badType.push(`${x.id} is not true or false`);
+        }
+        if (dup.length)
+            add('tunables', 'warn', `ids listed twice: ${list(dup)}`, 'an id is used once, never reused');
+        if (noDefault.length)
+            add('tunables', 'warn', `no default: ${list(noDefault)}`);
+        if (outside.length)
+            add('tunables', 'warn', `a default outside its own range: ${list(outside, 4)}`, 'move the default or widen the range, and say why');
+        if (badType.length)
+            add('tunables', 'warn', list(badType, 4));
+        const tests = walkFiles(root, 'test', (n) => /\.(m?[jt]s)$/.test(n)).map((p) => read(join(root, p))).join('\n') + specText;
+        const unknownTests = [...new Set(table.flatMap((x) => x.tests))].filter((name) => !tests.includes(name));
+        if (unknownTests.length)
+            add('tunables', 'warn', `tests a tunable names that no test file or spec file holds: ${list(unknownTests)}`, 'write the test, or take the name off the tunable');
+        const no = (k) => table.filter((x) => !x[k] && (k !== 'range' || typeof x.default === 'number')).length;
+        const gaps = ['why', 'unit', 'range'].map((k) => [k, no(k)]).filter(([, n]) => n);
+        if (gaps.length)
+            add('tunables', 'note', `of ${table.length} tunables: ${gaps.map(([k, n]) => `${n} with no ${k}`).join(', ')}`, 'a number with no why gets tuned by feel and drifts; a range says how far a lane may move it');
+        if (!dup.length && !noDefault.length && !outside.length && !badType.length && !unknownTests.length && !t.problems.length)
+            add('tunables', 'ok', `${table.length} tunables, each with a default${table.some((x) => x.range) ? ' inside its range' : ''}`);
+    }
+    const ids = byId(table);
+    const groups = new Set(table.map((x) => x.group));
+    const srcFiles = walkFiles(root, srcDir, (n) => /\.(tsx?|jsx?|mjs)$/.test(n) && !/\.d\.ts$/.test(n));
+    const sources = srcFiles.map((p) => ({ p, text: code(read(join(root, p))) }));
+    const roomData = uniqueRooms(specRooms(root, specDir).rooms);
+    const cited = new Set();
+    const unknown = [];
+    if (!sources.length)
+        add('unknown', 'not measured', `no ${srcDir}/ here: the code's reads are not checked`);
+    else {
+        for (const { p, text } of sources) {
+            for (const m of text.matchAll(/\btune\(\s*['"`]([^'"`]+)['"`]\s*\)/g)) {
+                cited.add(m[1]);
+                if (!ids.has(m[1]))
+                    unknown.push(`${p}: tune('${m[1]}')`);
+            }
+            for (const m of text.matchAll(/\bgroup\(\s*['"`]([^'"`]+)['"`]\s*\)/g))
+                if (!groups.has(m[1]))
+                    unknown.push(`${p}: group('${m[1]}')`);
+        }
+    }
+    for (const r of roomData)
+        for (const k of Object.keys(r.tune ?? {}))
+            if (!ids.has(k))
+                unknown.push(`room ${r.id} sets ${k}`);
+    const specCites = new Set();
+    for (const m of specText.matchAll(/(?<![A-Za-z0-9-])TUNE-[A-Z0-9][A-Z0-9-]*\*?/g))
+        specCites.add(m[0].replace(/-$/, ''));
+    const proposed = new Set([...specText.matchAll(/(?<![A-Za-z0-9-])P-(TUNE-[A-Z0-9][A-Z0-9-]*[A-Z0-9])/g)].map((m) => m[1]));
+    for (const m of specText.matchAll(/`([a-z][\w]*)\.([A-Za-z_][\w]*)`/g))
+        if (groups.has(m[1]) && !FILE_EXT.test(m[2]))
+            specCites.add(`${m[1]}.${m[2]}`);
+    const listIds = [...ids.keys()];
+    for (const c of specCites) {
+        const ok = c.endsWith('*') ? listIds.some((i) => i.startsWith(c.slice(0, -1))) : ids.has(c);
+        if (!ok)
+            unknown.push(`a spec file cites ${c}`);
+    }
+    if (proposed.size)
+        add('unknown', 'note', `${proposed.size} proposed id${proposed.size === 1 ? '' : 's'} (P-TUNE-…) cited, not in tunables.json yet${names.some((n) => /^tunables-.+\.json$/i.test(n)) ? ` (${names.filter((n) => /^tunables-.+\.json$/i.test(n)).join(', ')} holds proposals)` : ''}`, 'adopt each into tunables.json when its lane lands, or drop it');
+    if (table.length) {
+        if (unknown.length)
+            add('unknown', 'warn', `${unknown.length} cited id${unknown.length === 1 ? '' : 's'} the tunables do not have: ${list(unknown)}`, 'add the tunable (default, unit, range, why), or fix the name');
+        else
+            add('unknown', 'ok', `every id cited is a tunable (${sources.length ? 'the code, ' : ''}the rooms${specCites.size ? `, ${specCites.size} citations in the spec files` : ''})`);
+    }
+    if (sources.length && table.length) {
+        const all = sources.map((s) => s.text).join('\n');
+        const groupRead = new Set([...all.matchAll(/\bgroup\(\s*['"`]([^'"`]+)['"`]\s*\)/g)].map((m) => m[1]));
+        const token = (n) => new RegExp(`(?:\\.|\\b)${n.replace(/[$]/g, '\\$')}\\b`);
+        const unused = table.filter((x) => !all.includes(`'${x.id}'`) && !all.includes(`"${x.id}"`) && !(groupRead.has(x.group) && token(x.name).test(all))).map((x) => x.id);
+        if (unused.length)
+            add('unused', 'warn', `${unused.length} of ${table.length} tunables the code never reads: ${list(unused)}`, 'read it (tune(\'id\'), or group(\'name\') and the field), or take it out: a number nothing reads is a promise the game does not keep');
+        else
+            add('unused', 'ok', `the code reads every tunable (${table.length})`);
+        const byName = new Map(), byKey = new Map();
+        const put = (m, k, x) => { if (k.length >= 3)
+            m.set(k, [...(m.get(k) ?? []), x]); };
+        for (const x of table) {
+            put(byName, norm(`${x.group}${x.name}`), x);
+            if (!x.id.includes('.'))
+                put(byName, norm(x.id.replace(/^TUNE-/, '')), x);
+            else if (norm(x.name).length >= 5 && !(typeof x.default === 'number' && Math.abs(x.default) <= 2 && Number.isInteger(x.default)))
+                put(byKey, norm(x.name), x);
+        }
+        const typed = [];
+        for (const { p, text } of sources) {
+            const lines = text.split('\n');
+            lines.forEach((line, i) => {
+                for (const m of line.matchAll(/\b([A-Za-z_$][\w$]*)\s*(?:=|:)\s*(-?\d[\d_]*\.?\d*(?:e[-+]?\d+)?)\b(?!\s*[*/+-]\s*\d)/g)) {
+                    const value = Number(m[2].replace(/_/g, ''));
+                    const hit = [...(byName.get(norm(m[1])) ?? []), ...(byKey.get(norm(m[1])) ?? [])].find((x) => x.default === value);
+                    if (hit)
+                        typed.push(`${p}:${i + 1} ${m[1]} = ${m[2]} is ${hit.id}`);
+                }
+            });
+        }
+        if (typed.length)
+            add('typed in', 'warn', `${typed.length} number${typed.length === 1 ? '' : 's'} typed into the code that ${typed.length === 1 ? 'is a tunable' : 'are tunables'}: ${list(typed, 4)}`, 'read it from tunables.json (tune(\'id\') where it is used, or group(\'name\') for a table) so the file stays the one source');
+        else
+            add('typed in', 'ok', 'no tunable\'s number is typed into the code under its name');
+    }
+    else if (table.length)
+        add('unused', 'not measured', `no ${srcDir}/ here: which tunables the game reads is not checked`);
+    const prose = [];
+    for (const n of mdFiles) {
+        const body = read(join(root, specDir, n)).replace(/```[\s\S]*?```/g, '').replace(/<!--[\s\S]*?-->/g, '');
+        for (const m of body.matchAll(/(?<![A-Za-z0-9.:-])(\d+(?:\.\d+)?)\s?(ms|s|m|m\/s|deg|°|px|%|Hz|LUFS|dB)(?![A-Za-z0-9])/g))
+            prose.push(`${n}: "${m[0]}"`);
+    }
+    if (prose.length)
+        add('numbers in prose', 'note', `${prose.length} number${prose.length === 1 ? '' : 's'} with a unit in the spec's prose: ${list(prose, 4)}`, 'cite the tunable\'s id instead, so the number has one home');
+    const rooms = roomData;
+    let parTotal = 0;
+    if (!rooms.length)
+        add('rooms', o.tier ? 'warn' : 'not measured', `no rooms as data (${specDir}/rooms.json)`, 'funtools spec init writes rooms.json; a room is a par, an exit, what it teaches and its numbers');
+    else {
+        const at = new Set(rooms.map((r) => r.id));
+        const noPar = rooms.filter((r) => r.par === null).map((r) => r.id), noExit = rooms.filter((r) => !r.exit).map((r) => r.id);
+        const badExit = rooms.filter((r) => r.exit && r.exit !== END && r.exit !== 'doors' && !at.has(r.exit)).map((r) => `${r.id} → ${r.exit}`);
+        if (noPar.length)
+            add('rooms', 'warn', `no par (the seconds a good first run takes): ${list(noPar)}`, 'give each room a par: the pars are the game\'s length');
+        if (noExit.length)
+            add('rooms', 'warn', `no exit: ${list(noExit)}`, `name the room it opens onto, or "${END}" after the last`);
+        if (badExit.length)
+            add('rooms', 'warn', `an exit to a room that is not there: ${list(badExit)}`);
+        const chained = rooms.every((r) => r.exit && r.exit !== 'doors');
+        if (chained && !badExit.length) {
+            const seen = new Set();
+            for (let r = rooms[0]; r && !seen.has(r.id); r = rooms.find((x) => x.id === r.exit))
+                seen.add(r.id);
+            const lost = rooms.filter((r) => !seen.has(r.id)).map((r) => r.id);
+            if (lost.length)
+                add('rooms', 'warn', `no exit leads to ${list(lost)} from the first room`, 'chain them: each room\'s exit is the next');
+        }
+        else if (!chained)
+            add('rooms', 'note', 'exits are door positions, not rooms: the order of play is the list\'s');
+        const withPar = rooms.filter((r) => r.par !== null);
+        parTotal = withPar.reduce((s, r) => s + (r.par ?? 0), 0);
+        if (!noPar.length && !noExit.length && !badExit.length)
+            add('rooms', 'ok', `${rooms.length} rooms, each with a par and an exit${withPar.some((r) => r.parFrom && r.parFrom !== 'the room') ? ' (pars read from the tunables)' : ''}`);
+        const of = withPar.length < rooms.length ? ` (${withPar.length} of ${rooms.length} rooms have one)` : '';
+        if (parTotal < o.floor.seconds)
+            add('length', 'warn', `the pars add up to ${clock(parTotal)}${of}, under the play floor of ${clock(o.floor.seconds)} (${o.floor.where})`, 'more rooms, or bigger ones, until the pars reach the floor; a smaller game says so on purpose (funpixel.json play_min_minutes)');
+        else
+            add('length', 'ok', `the pars add up to ${clock(parTotal)}${of}, at or over the play floor of ${clock(o.floor.seconds)}`);
+        const early = builtEarly(readOpen(root), rooms);
+        if (early.length)
+            add('slice', 'warn', `${list(early.map((r) => r.id))} changed before ${early.length === 1 ? 'it was' : 'they were'} opened: slice first`, `put it back as planned, or open it in turn: funtools rooms open ${early[0].id} (the owner can release it: --by owner)`);
+    }
+    const counts = { warn: 0, note: 0, ok: 0, 'not measured': 0 };
+    for (const x of f)
+        counts[x.state]++;
+    return { findings: f, counts, tier: o.tier, tunables: table.length, rooms: rooms.length, parTotal, floor: o.floor };
+}
+export const hasSpec = (root, specDir = SPEC_DIR) => existsSync(join(root, specDir));

package/dist/spec/presets.js

@@ -0,0 +1,30 @@
+const TRACK = [
+    { id: 'c1', name: 'The first track', rooms: [
+            { id: 'r1-1', name: 'First light', slice: true, par: 120, waves: 5, teaches: 'step onto a gem to take it; hop a spike late in its glow', beat: 'the first spike', tune: { 'rules.goal': 60, 'rules.round_seconds': 75, 'respawn.seconds': 2, 'spike.first': 12, 'spike.every': 4 } },
+            { id: 'r1-2', name: 'The long row', par: 150, waves: 7, teaches: 'gems come back slower: keep moving along the row', beat: 'spikes at the starter\'s pace', tune: { 'rules.goal': 60, 'rules.round_seconds': 75, 'respawn.seconds': 2.5 } },
+            { id: 'r1-3', name: 'Quick cracks', par: 150, waves: 7, teaches: 'read the glow: a shorter tell asks for an earlier hop', beat: 'the tell shortens', tune: { 'rules.goal': 60, 'rules.round_seconds': 75, 'respawn.seconds': 2.5, 'rules.tell_seconds': 0.5 } },
+        ] },
+    { id: 'c2', name: 'The night track', rooms: [
+            { id: 'r2-1', name: 'Slow returns', par: 150, waves: 6, teaches: 'gems come back slowly: plan the loop, not the next gem', beat: 'the track empties', tune: { 'rules.goal': 50, 'rules.round_seconds': 75, 'respawn.seconds': 5 } },
+            { id: 'r2-2', name: 'Rush hour', par: 150, waves: 6, teaches: 'spikes close together: hop, land, step, hop', beat: 'spikes back to back', tune: { 'rules.goal': 50, 'rules.round_seconds': 75, 'respawn.seconds': 5, 'spike.every': 1.8 } },
+            { id: 'r2-3', name: 'The last row', par: 190, waves: 8, teaches: 'everything at once, the longest run', beat: 'the finale', tune: { 'rules.goal': 50, 'rules.round_seconds': 75, 'respawn.seconds': 5, 'spike.every': 1.6, 'rules.tell_seconds': 0.5 } },
+        ] },
+];
+const SQUARE = [
+    { id: 'c1', name: 'The square', rooms: [
+            { id: 'r1-1', name: 'First lights', slice: true, par: 130, waves: 6, teaches: 'run to a light to take it; jump up to the high ones', beat: 'the first flare', tune: { 'rules.goal': 16, 'flare.first': 12, 'flare.every': 4 } },
+            { id: 'r1-2', name: 'Rings', par: 150, waves: 6, teaches: 'a ring glows under you: run out of it, or jump as it flares', beat: 'flares every few seconds', tune: { 'rules.goal': 20, 'rules.round_seconds': 60, 'flare.every': 3 } },
+            { id: 'r1-3', name: 'The wide square', par: 150, waves: 5, teaches: 'a bigger square: route between the lights', beat: 'the square grows', tune: { 'rules.goal': 20, 'rules.round_seconds': 70, 'layout.arena': 19, 'flare.every': 3 } },
+        ] },
+    { id: 'c2', name: 'The night square', rooms: [
+            { id: 'r2-1', name: 'Quick flares', par: 150, waves: 6, teaches: 'a shorter glow: move at the first sign', beat: 'the tell shortens', tune: { 'rules.goal': 20, 'rules.round_seconds': 60, 'flare.tell': 0.55, 'flare.every': 2.5 } },
+            { id: 'r2-2', name: 'High ground', par: 150, waves: 5, teaches: 'more platforms, more lights up high', beat: 'the climb', tune: { 'rules.goal': 24, 'rules.round_seconds': 70, 'layout.boxes': 10, 'flare.every': 2.5 } },
+            { id: 'r2-3', name: 'The last lights', par: 170, waves: 5, teaches: 'everything at once, the longest run', beat: 'the finale', tune: { 'rules.goal': 24, 'rules.round_seconds': 75, 'layout.arena': 19, 'flare.tell': 0.55, 'flare.every': 2.2 } },
+        ] },
+];
+export const presetFor = (framework) => (framework === 'three-world' ? SQUARE : TRACK);
+export function fitPreset(chapters, ids) {
+    const dropped = new Set();
+    const out = chapters.map((c) => ({ ...c, rooms: c.rooms.map((r) => ({ ...r, tune: Object.fromEntries(Object.entries(r.tune).filter(([k]) => (ids.has(k) ? true : (dropped.add(k), false)))) })) }));
+    return { chapters: out, dropped: [...dropped] };
+}

package/dist/spec/rooms.js

@@ -0,0 +1,188 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { byId, readTunables, SPEC_DIR } from "./tunables.js";
+import { playFloor } from "../sim/judge.js";
+export const ROOMS_RECORD = join('.funtools', 'rooms.json');
+export const OPEN_FILE = join('.funtools', 'rooms-open.json');
+export const END = 'end';
+export const PAR_BAND = 0.5;
+export const ROOM_SEEDS = 5;
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+const sha = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
+export function roomFiles(root, specDir = SPEC_DIR) {
+    let names = [];
+    try {
+        names = readdirSync(join(root, specDir));
+    }
+    catch {
+        return [];
+    }
+    return names.filter((n) => /(^|[-_])rooms[^/]*\.json$/i.test(n)).sort().map((n) => join(specDir, n));
+}
+function parOf(raw, id, tunables) {
+    if (typeof raw.par === 'number' && raw.par > 0)
+        return { par: raw.par, parFrom: 'the room' };
+    const num = (t) => (t && typeof t.default === 'number' && t.default > 0 ? t.default : null);
+    if (typeof raw.par === 'string') {
+        const t = tunables.get(raw.par);
+        return { par: num(t), parFrom: raw.par };
+    }
+    const want = id.toUpperCase().replace(/[^A-Z0-9]+/g, '-');
+    for (const t of tunables.values()) {
+        if (new RegExp(`(^|-)ROOM-${want}-PAR$`, 'i').test(t.id) || t.id === `rooms.${id}_par`)
+            return { par: num(t), parFrom: t.id };
+    }
+    return { par: null };
+}
+function exitOf(raw) {
+    if (typeof raw.exit === 'string' && raw.exit.trim())
+        return raw.exit.trim();
+    if (Array.isArray(raw.exits) && raw.exits.length)
+        return 'doors';
+    return null;
+}
+export function specRooms(root, specDir = SPEC_DIR) {
+    const files = roomFiles(root, specDir), problems = [], rooms = [];
+    const t = readTunables(root, specDir);
+    const tunables = 'list' in t ? byId(t.list) : new Map();
+    for (const file of files) {
+        const data = readJson(join(root, file));
+        if (!data) {
+            problems.push(`${file} is not JSON`);
+            continue;
+        }
+        const chapters = Array.isArray(data.chapters)
+            ? data.chapters.map((c) => ({ id: String(c?.id ?? '?'), rooms: Array.isArray(c?.rooms) ? c.rooms : [] }))
+            : Array.isArray(data.rooms) ? [{ id: 'rooms', rooms: data.rooms }] : [];
+        if (!chapters.length)
+            problems.push(`${file} has neither "chapters" nor "rooms"`);
+        for (const c of chapters)
+            for (const r of c.rooms) {
+                if (!r || typeof r !== 'object' || typeof r.id !== 'string' || !r.id) {
+                    problems.push(`${file}: a room without an id`);
+                    continue;
+                }
+                rooms.push({
+                    id: r.id, name: typeof r.name === 'string' ? r.name : r.id, chapter: c.id, ...parOf(r, r.id, tunables), exit: exitOf(r),
+                    slice: r.slice === true, ...(typeof r.teaches === 'string' ? { teaches: r.teaches } : {}),
+                    ...(r.tune && typeof r.tune === 'object' ? { tune: r.tune } : {}), file, hash: sha(JSON.stringify(r)),
+                });
+            }
+    }
+    return { rooms, files, problems };
+}
+export function uniqueRooms(rooms) {
+    const at = new Map(), out = [];
+    for (const r of rooms) {
+        const i = at.get(r.id);
+        if (i === undefined) {
+            at.set(r.id, out.length);
+            out.push(r);
+        }
+        else
+            out[i] = r;
+    }
+    return out;
+}
+export const sliceRoom = (rooms) => rooms.find((r) => r.slice) ?? rooms[0] ?? null;
+export function readOpen(root) {
+    const r = readJson(join(root, OPEN_FILE));
+    return { version: 1, planned: r?.planned && typeof r.planned === 'object' ? r.planned : {}, opened: Array.isArray(r?.opened) ? r.opened : [] };
+}
+export const isOpened = (rec, rooms, id) => sliceRoom(rooms)?.id === id || rec.opened.some((o) => o.room === id);
+export function builtEarly(rec, rooms) {
+    return rooms.filter((r) => !isOpened(rec, rooms, r.id) && rec.planned[r.id] !== undefined && rec.planned[r.id] !== r.hash);
+}
+export const readRoomsRecord = (root) => {
+    const r = readJson(join(root, ROOMS_RECORD));
+    return r && Array.isArray(r.rooms) ? r : null;
+};
+export function specHash(root) {
+    const h = createHash('sha256');
+    const walk = (rel, depth) => {
+        let names = [];
+        try {
+            names = readdirSync(join(root, rel)).sort();
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            if (n === 'node_modules' || n.startsWith('.'))
+                continue;
+            const p = join(rel, n);
+            let st;
+            try {
+                st = statSync(join(root, p));
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (depth < 6)
+                    walk(p, depth + 1);
+            }
+            else {
+                try {
+                    h.update(p).update('\0').update(readFileSync(join(root, p))).update('\n');
+                }
+                catch { }
+            }
+        }
+    };
+    walk(SPEC_DIR, 0);
+    walk('src', 0);
+    return `sha256:${h.digest('hex').slice(0, 32)}`;
+}
+export function lengthFromRooms(root, fp, floor) {
+    const rec = readRoomsRecord(root);
+    if (!rec || (fp && rec.fingerprint && rec.fingerprint !== fp))
+        return null;
+    const played = rec.played_total;
+    if (typeof played !== 'number')
+        return null;
+    const says = `play length from the rooms: a careful player's whole campaign of ${rec.rooms.length} rooms takes ${mmss(played)} (pars ${mmss(rec.par_total)}; ${ROOMS_RECORD}) against the bar (${mmss(floor.seconds)} for ${floor.where}); one round is one wave`;
+    return played >= floor.seconds ? { state: 'ok', says } : { state: 'warn', says, next: 'more rooms, more waves, or bigger rooms in design/spec/rooms.json until the campaign reaches the floor; then funtools rooms' };
+}
+const mmss = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+export const clock = mmss;
+const T = 'npx @funpixel/tools';
+export function roomsGate(root, fp) {
+    const { rooms: all } = specRooms(root);
+    const rooms = uniqueRooms(all);
+    const closes = `${ROOMS_RECORD} on the current files: every room opened in turn and cleared by the careful player on ${ROOM_SEEDS} seeds within its par, the pars adding up to the play floor`;
+    if (!rooms.length)
+        return { state: 'open', says: 'no rooms as data yet (design/spec/rooms.json)', closes, run: `${T} spec init (the big tier's spec folder, rooms and the room runner), then ${T} rooms` };
+    const open = readOpen(root);
+    const early = builtEarly(open, rooms);
+    if (early.length)
+        return { state: 'failing', says: `${early.map((r) => r.id).join(', ')} changed before ${early.length === 1 ? 'it was' : 'they were'} opened (slice first: a room waits until the one before it passes)`, closes, run: `put ${early.length === 1 ? 'it' : 'them'} back as planned, or open in turn: ${T} rooms open ${early[0].id} (the owner can release it: --by owner)` };
+    const rec = readRoomsRecord(root);
+    if (!rec)
+        return { state: 'open', says: 'the bots never played the rooms', closes, run: `${T} rooms` };
+    if (fp && rec.fingerprint && rec.fingerprint !== fp)
+        return { state: 'stale', says: 'the rooms were played on older files', closes, run: `${T} rooms` };
+    const row = (id) => rec.rooms.find((r) => r.id === id);
+    for (const r of rooms) {
+        const got = row(r.id);
+        if (!isOpened(open, rooms, r.id)) {
+            const prev = rooms[rooms.indexOf(r) - 1];
+            return { state: 'open', says: `${r.id} is next${prev ? `: ${prev.id} passes` : ''}`, closes, run: `${T} rooms open ${r.id}, build it, then ${T} rooms` };
+        }
+        if (!got)
+            return { state: 'open', says: `${r.id} was not played`, closes, run: `${T} rooms` };
+        if (got.verdict !== 'pass')
+            return { state: 'failing', says: `${r.id}: ${got.says}`, closes, run: `fix ${r.id} (its data in ${r.file}, the rules, or its par), then ${T} rooms` };
+    }
+    const floor = playFloor(root);
+    const total = rooms.reduce((s, r) => s + (r.par ?? 0), 0);
+    if (total < floor.seconds)
+        return { state: 'failing', says: `the pars add up to ${mmss(total)}, under the floor of ${mmss(floor.seconds)} (${floor.where})`, closes, run: 'add rooms, or grow the rooms you have, until the pars reach the floor; then funtools rooms' };
+    return { state: 'met', says: `${rooms.length} rooms cleared in turn on ${rec.seeds} seeds; pars ${mmss(total)} against the floor ${mmss(floor.seconds)}`, closes: '', run: '' };
+}