@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/doctor/host.js

@@ -0,0 +1,245 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const HOSTS = ['claude', 'codex', 'cursor', 'kiro'];
+export const HOST_LABEL = { claude: 'Claude Code', codex: 'Codex', cursor: 'Cursor CLI', kiro: 'Kiro CLI' };
+export function detectHost(env = process.env) {
+    if (env.CLAUDECODE === '1')
+        return { host: 'claude', why: 'CLAUDECODE=1' };
+    for (const v of ['CODEX_SANDBOX', 'CODEX_SANDBOX_NETWORK_DISABLED', 'CODEX_THREAD_ID'])
+        if (env[v])
+            return { host: 'codex', why: `${v} is set` };
+    if (env.CURSOR_AGENT === '1')
+        return { host: 'cursor', why: 'CURSOR_AGENT=1' };
+    return null;
+}
+export const KIT_COMMANDS = [
+    { cmd: 'npx @funpixel/tools verify', what: 'every funtools verb (check, verify, capture, gen, …)' },
+    { cmd: 'npm install', what: 'dependencies (needs the network)' },
+    { cmd: 'npm run build', what: 'the build' },
+    { cmd: 'npm test', what: 'the rules suite' },
+    { cmd: 'node tools/bot.ts', what: 'a script of your own (bots, solvers)' },
+];
+export const SHAPES = [
+    { shape: 'a chain (&&)', example: 'npm run build && npx @funpixel/tools verify', instead: '`funtools check` (build, test, verify in one call), or one command per call' },
+    { shape: 'a heredoc', example: "cat >> .funtools/devlog.jsonl <<'EOF'", instead: 'the Write or Edit tool; `funtools feedback log "…"` for the dev log' },
+    { shape: 'a substitution', example: 'echo "$(date)"', instead: 'one command per call; funtools stamps times itself' },
+    { shape: 'a loop', example: 'for f in public/assets/*.png; do file "$f"; done', instead: 'verbs that take many files: `optimize compress a.png b.png`, `capture --all`' },
+    { shape: 'python', example: "python3 -c 'print(1)'", instead: '`node file.ts` (TypeScript runs as is on Node 22.18+), or a funtools verb' },
+];
+const readJson = (path) => {
+    if (!existsSync(path))
+        return { found: false, data: null };
+    try {
+        return { found: true, data: JSON.parse(readFileSync(path, 'utf8')) };
+    }
+    catch (e) {
+        return { found: true, data: null, problem: `not JSON: ${e instanceof Error ? e.message : e}` };
+    }
+};
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+export const subcommands = (cmd) => cmd.split(/&&|\|\||;|\|&?|\n/).map((s) => s.trim()).filter(Boolean);
+const glob = (pattern) => new RegExp(`^${pattern.split('*').map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
+export function claudeRuleMatches(rule, cmd) {
+    if (rule === 'Bash' || rule === 'Bash(*)')
+        return true;
+    const m = /^Bash\((.*)\)$/s.exec(rule);
+    if (!m)
+        return false;
+    const p = m[1];
+    if (p.endsWith(':*')) {
+        const pre = p.slice(0, -2);
+        return cmd === pre || cmd.startsWith(`${pre} `);
+    }
+    if (p.endsWith(' *') && cmd === p.slice(0, -2))
+        return true;
+    return p.includes('*') ? glob(p).test(cmd) : cmd === p;
+}
+function claudeVerdict(cmd, allow, deny, mode) {
+    const parts = subcommands(cmd);
+    if (parts.some((c) => deny.some((r) => claudeRuleMatches(r, c))))
+        return 'denied';
+    if (mode === 'bypassPermissions')
+        return 'allowed';
+    return parts.every((c) => allow.some((r) => claudeRuleMatches(r, c))) ? 'allowed' : 'not covered';
+}
+const CLAUDE_LINES = ['Bash(npx @funpixel/tools *)', 'Bash(npm install)', 'Bash(npm run *)', 'Bash(npm test)', 'Bash(node *)'];
+function claude({ dir, home }) {
+    const paths = [join(home, '.claude', 'settings.json'), join(dir, '.claude', 'settings.json'), join(dir, '.claude', 'settings.local.json')];
+    const files = [];
+    const allow = [], deny = [];
+    let mode, sandbox;
+    for (const path of paths) {
+        const r = readJson(path);
+        files.push({ path, found: r.found, ...(r.problem ? { problem: r.problem } : {}) });
+        const p = r.data?.permissions;
+        allow.push(...strings(p?.allow));
+        deny.push(...strings(p?.deny));
+        if (typeof p?.defaultMode === 'string')
+            mode = p.defaultMode;
+        if (typeof r.data?.sandbox?.enabled === 'boolean')
+            sandbox = r.data.sandbox.enabled;
+    }
+    const notes = [`permission mode: ${mode ?? 'default (asks; a run with prompts off refuses instead)'}${mode === 'auto' ? ' (a classifier reviews what no rule covers)' : ''}`];
+    if (sandbox)
+        notes.push('sandbox on: commands run with file and network limits; npm install, gen and publish need the network');
+    const judge = (cmd) => claudeVerdict(cmd, allow, deny, mode);
+    const commands = KIT_COMMANDS.map((k) => ({ cmd: k.cmd, what: k.what, status: judge(k.cmd), why: 'each part checked against permissions.allow / deny' }));
+    const shapes = SHAPES.map((s) => {
+        const opaque = /<<|\$\(|\bfor\b/.test(s.example);
+        return { cmd: s.example, what: s.shape, instead: s.instead, status: opaque ? 'unknown' : judge(s.example),
+            why: opaque ? 'Claude Code checks each command inside it, and the file it writes, on its own; it may still ask' : 'each part checked against permissions.allow / deny' };
+    });
+    const missing = CLAUDE_LINES.filter((line) => !allow.includes(line) && KIT_COMMANDS.some((k) => claudeRuleMatches(line, k.cmd) && judge(k.cmd) === 'not covered'));
+    return {
+        host: 'claude', label: HOST_LABEL.claude, files, notes, commands, shapes,
+        add: missing.length ? { where: `"permissions": { "allow": [...] } in ${join(dir, '.claude', 'settings.local.json')} (you, this game) or ${join(home, '.claude', 'settings.json')} (every project)`, lines: missing.map((l) => JSON.stringify(l)) } : null,
+        caveat: 'a --allowedTools flag, a managed policy or a permission mode set on the command line is not in these files',
+    };
+}
+export function codexRules(text) {
+    const out = [];
+    for (const m of text.matchAll(/prefix_rule\s*\(([\s\S]*?)\)/g)) {
+        const pat = /pattern\s*=\s*\[([^\]]*)\]/.exec(m[1]);
+        const dec = /decision\s*=\s*"(\w+)"/.exec(m[1]);
+        if (!pat)
+            continue;
+        const pattern = [...pat[1].matchAll(/"([^"]*)"/g)].map((x) => x[1]);
+        if (pattern.length)
+            out.push({ pattern, decision: dec?.[1] ?? 'allow' });
+    }
+    return out;
+}
+const tokens = (cmd) => cmd.split(/\s+/).filter(Boolean);
+function codexVerdict(cmd, rules) {
+    if (/[<>$`*]|\bfor\b|\bwhile\b/.test(cmd))
+        return 'unknown';
+    const one = (c) => {
+        const t = tokens(c);
+        const hit = rules.filter((r) => r.pattern.every((p, i) => t[i] === p));
+        if (hit.some((r) => r.decision === 'forbidden'))
+            return 'denied';
+        return hit.some((r) => r.decision === 'allow') ? 'allowed' : 'not covered';
+    };
+    const parts = subcommands(cmd).map(one);
+    return parts.includes('denied') ? 'denied' : parts.every((s) => s === 'allowed') ? 'allowed' : 'not covered';
+}
+const CODEX_LINES = [['npx', '@funpixel/tools'], ['npm', 'install'], ['npm', 'run'], ['npm', 'test'], ['node']];
+function codex({ home, env }) {
+    const root = env.CODEX_HOME || join(home, '.codex');
+    const config = join(root, 'config.toml');
+    const files = [{ path: config, found: existsSync(config) }];
+    const toml = files[0].found ? readFileSync(config, 'utf8') : '';
+    const key = (k) => new RegExp(`^\\s*${k}\\s*=\\s*"?([\\w-]+)"?`, 'm').exec(toml)?.[1];
+    const sandbox = key('sandbox_mode'), approval = key('approval_policy');
+    const network = /\[sandbox_workspace_write\][^[]*network_access\s*=\s*true/.test(toml);
+    const rulesDir = join(root, 'rules');
+    const rules = [];
+    if (existsSync(rulesDir)) {
+        for (const f of readdirSync(rulesDir).filter((f) => f.endsWith('.rules')).sort()) {
+            const path = join(rulesDir, f);
+            files.push({ path, found: true });
+            rules.push(...codexRules(readFileSync(path, 'utf8')));
+        }
+    }
+    else
+        files.push({ path: join(rulesDir, '*.rules'), found: false });
+    const notes = [`sandbox_mode: ${sandbox ?? 'not set (Codex default)'}`, `approval_policy: ${approval ?? 'not set (Codex default)'}`];
+    if ((sandbox ?? 'workspace-write') === 'workspace-write' && !network) {
+        notes.push('in the workspace-write sandbox (the usual one) the network is off: npm install, gen and publish need it — `[sandbox_workspace_write]` `network_access = true` in config.toml, or run those yourself');
+    }
+    const commands = KIT_COMMANDS.map((k) => ({ cmd: k.cmd, what: k.what, status: codexVerdict(k.cmd, rules), why: 'prefix rules in rules/*.rules' }));
+    const shapes = SHAPES.map((s) => {
+        const status = codexVerdict(s.example, rules);
+        return { cmd: s.example, what: s.shape, instead: s.instead, status, why: status === 'unknown' ? 'judged as one `bash -lc` call, which a prefix rule does not match' : 'each part checked against the prefix rules' };
+    });
+    const missing = CODEX_LINES.filter((p) => KIT_COMMANDS.some((k) => p.every((t, i) => tokens(k.cmd)[i] === t) && codexVerdict(k.cmd, rules) === 'not covered'));
+    return {
+        host: 'codex', label: HOST_LABEL.codex, files, notes, commands, shapes,
+        add: missing.length ? { where: `${join(rulesDir, 'funpixel.rules')} (a new file of your own)`, lines: missing.map((p) => `prefix_rule(pattern = [${p.map((t) => JSON.stringify(t)).join(', ')}], decision = "allow")`) } : null,
+        caveat: 'a --sandbox or --ask-for-approval flag, a profile or team config can override these files',
+    };
+}
+export function cursorRuleMatches(rule, cmd) {
+    const m = /^Shell\((.*)\)$/.exec(rule);
+    if (!m)
+        return false;
+    const [base, args] = m[1].split(/:(.*)/s);
+    const t = tokens(cmd);
+    if (!glob(base).test(t[0] ?? ''))
+        return false;
+    return args === undefined || glob(args).test(t.slice(1).join(' '));
+}
+function cursor({ dir, home }) {
+    const paths = [join(home, '.cursor', 'cli-config.json'), join(dir, '.cursor', 'cli.json')];
+    const files = [];
+    const allow = [], deny = [];
+    for (const path of paths) {
+        const r = readJson(path);
+        files.push({ path, found: r.found, ...(r.problem ? { problem: r.problem } : {}) });
+        allow.push(...strings(r.data?.permissions?.allow));
+        deny.push(...strings(r.data?.permissions?.deny));
+    }
+    const judge = (cmd) => {
+        if (/<<|\$\(|\bfor\b/.test(cmd))
+            return 'unknown';
+        const parts = subcommands(cmd);
+        if (parts.some((c) => deny.some((r) => cursorRuleMatches(r, c))))
+            return 'denied';
+        return parts.every((c) => allow.some((r) => cursorRuleMatches(r, c))) ? 'allowed' : 'not covered';
+    };
+    const commands = KIT_COMMANDS.map((k) => ({ cmd: k.cmd, what: k.what, status: judge(k.cmd), why: 'the first word against permissions.allow / deny' }));
+    const shapes = SHAPES.map((s) => ({ cmd: s.example, what: s.shape, instead: s.instead, status: judge(s.example), why: 'the documentation does not say how a chain or heredoc is judged' }));
+    const lines = ['Shell(npx)', 'Shell(npm)', 'Shell(node)'].filter((l) => !allow.includes(l) && KIT_COMMANDS.some((k) => cursorRuleMatches(l, k.cmd) && judge(k.cmd) === 'not covered'));
+    return {
+        host: 'cursor', label: HOST_LABEL.cursor, files, notes: ['Shell(npx) lets any npx package run, not only @funpixel/tools: your call'], commands, shapes,
+        add: lines.length ? { where: `"permissions": { "allow": [...] } in ${paths[1]} (this game) or ${paths[0]} (everywhere)`, lines: lines.map((l) => JSON.stringify(l)) } : null,
+        caveat: 'the IDE agent and the CLI keep separate settings; this reads the CLI\'s',
+    };
+}
+function kiro({ dir, home, env }) {
+    const global = join(env.KIRO_HOME || join(home, '.kiro'), 'agents', 'funpixel.json');
+    const paths = [global, join(dir, '.kiro', 'agents', 'funpixel.json')];
+    const files = [];
+    const allow = [], deny = [], legacy = [];
+    for (const path of paths) {
+        const r = readJson(path);
+        files.push({ path, found: r.found, ...(r.problem ? { problem: r.problem } : {}) });
+        for (const rule of Array.isArray(r.data?.permissions?.rules) ? r.data.permissions.rules : []) {
+            if (rule?.capability !== 'shell' && rule?.capability !== 'all')
+                continue;
+            (rule.effect === 'deny' ? deny : rule.effect === 'allow' ? allow : []).push(...strings(rule.match));
+        }
+        const shell = r.data?.toolsSettings?.shell ?? r.data?.toolsSettings?.execute_bash;
+        legacy.push(...strings(shell?.allowedCommands));
+    }
+    const judge = (cmd) => {
+        if (/<<|\$\(|\bfor\b/.test(cmd))
+            return 'unknown';
+        const parts = subcommands(cmd);
+        if (parts.some((c) => deny.some((p) => glob(p).test(c))))
+            return 'denied';
+        const ok = (c) => allow.some((p) => glob(p).test(c) || (p.endsWith(' *') && c === p.slice(0, -2))) || legacy.some((p) => { try {
+            return new RegExp(`^(?:${p})$`).test(c);
+        }
+        catch {
+            return false;
+        } });
+        return parts.every(ok) ? 'allowed' : 'not covered';
+    };
+    const commands = KIT_COMMANDS.map((k) => ({ cmd: k.cmd, what: k.what, status: judge(k.cmd), why: 'shell rules in the agent file' }));
+    const shapes = SHAPES.map((s) => ({ cmd: s.example, what: s.shape, instead: s.instead, status: judge(s.example), why: 'the documentation does not say how a chain or heredoc is judged' }));
+    const need = ['npx @funpixel/tools *', 'npm install', 'npm run *', 'npm test', 'node *'].filter((p) => KIT_COMMANDS.some((k) => (glob(p).test(k.cmd)) && judge(k.cmd) === 'not covered'));
+    return {
+        host: 'kiro', label: HOST_LABEL.kiro, files, notes: files.some((f) => f.found) ? [] : ['no funpixel agent file: install the GDK\'s Kiro package (node install.mjs) or point this at your own agent'], commands, shapes,
+        add: need.length ? {
+            where: `the agent file (${paths[0]}, or the workspace's): Kiro CLI 3.x "permissions": { "rules": [...] }; on 2.x, "toolsSettings": { "shell": { "allowedCommands": [${need.map((p) => JSON.stringify(p.replace(/ \*$/, ' .*'))).join(', ')}] } } (regular expressions, the whole command)`,
+            lines: [JSON.stringify({ capability: 'shell', match: need, effect: 'allow' })],
+        } : null,
+        caveat: 'Kiro CLI 3.x replaced toolsSettings with permissions; check `kiro-cli --version` for which one yours reads',
+    };
+}
+const READERS = { claude, codex, cursor, kiro };
+export function hostReport(host, dir, env = process.env, home = homedir()) {
+    return READERS[host]({ dir, home, env });
+}

package/dist/doctor/unity-checks.js

@@ -0,0 +1,380 @@
+import { closeSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { graphicsApis, methodAt, methodsOf, scalar, TARGET_NAME, yamlMap } from "./unity-project.js";
+const list = (xs, n = 3) => `${xs.slice(0, n).join(', ')}${xs.length > n ? `, … (${xs.length} in all)` : ''}`;
+const hasTarget = (p, ...t) => t.some((x) => p.targets.has(x));
+const runtime = (f) => !f.editor && !f.test;
+const usesUrp = (p) => !!p.manifest['com.unity.render-pipelines.universal'];
+const major = (v) => Number(/^(\d+)/.exec(v ?? '')?.[1] ?? 0);
+export const INPUT_HANDLER = { '0': 'the old Input Manager only', '1': 'the Input System package', '2': 'both' };
+export const INPUT_FIX = 'Edit > Project Settings > Player > Other Settings > Active Input Handling: "Input System Package (New)" or "Both" (activeInputHandler: 1 or 2 in ProjectSettings/ProjectSettings.asset)';
+export function checkInput(p) {
+    const h = scalar(p.settings, 'activeInputHandler');
+    if (h === null)
+        return p.settings ? [['note', 'input: no activeInputHandler in ProjectSettings.asset (Unity writes it on the next save)']] : [];
+    const mobile = ['ios', 'android'].filter((t) => p.targets.has(t)).map((t) => TARGET_NAME[t]);
+    if (h === '0' && mobile.length) {
+        return [['fail', `input: activeInputHandler is 0 (${INPUT_HANDLER['0']}) and the project builds for ${mobile.join(' and ')}: touch did not work in a player build — set ${INPUT_FIX}`]];
+    }
+    const out = [['pass', `input: ${INPUT_HANDLER[h] ?? `activeInputHandler ${h}`} (activeInputHandler ${h})`]];
+    if ((h === '1' || h === '2') && !p.manifest['com.unity.inputsystem']) {
+        out.push(['warn', `input: activeInputHandler is ${h} but Packages/manifest.json has no com.unity.inputsystem — add the package (the studio pins 1.20.0), or no input reaches the game`]);
+    }
+    return out;
+}
+const USES_TMP = /\b(?:using\s+TMPro\b|TMPro\s*\.|TextMeshPro(?:UGUI)?\b|TMP_Text\b|TMP_FontAsset\b)/;
+export function checkTmp(p) {
+    const users = p.code.filter((f) => USES_TMP.test(f.code)).map((f) => f.rel);
+    if (!users.length)
+        return [];
+    if (p.tmpSettings.length)
+        return [['pass', `TextMeshPro Essential Resources are here (${p.tmpSettings[0]})`]];
+    return [['fail', `TextMeshPro is used (${list(users, 2)}) but its Essential Resources are missing (no TMP Settings.asset in Assets or a package): CreateFontAsset returns null and text draws nothing — import them once in the Editor (Window > TextMeshPro > Import TMP Essential Resources) and commit Assets/TextMesh Pro; never through a batch-mode ImportPackage, which hangs`]];
+}
+const SCENE_CAMERA = /^--- !u!20 &/m;
+const SCENE_LISTENER = /^--- !u!81 &/m;
+const CODE_CAMERA = /\bAddComponent\s*<\s*Camera\s*>\s*\(|\bAddComponent\s*\(\s*typeof\s*\(\s*Camera\s*\)|\bnew\s+GameObject\s*\([^;]*typeof\s*\(\s*Camera\s*\)/;
+const CODE_LISTENER = /\bAddComponent\s*<\s*AudioListener\s*>\s*\(|\bAddComponent\s*\(\s*typeof\s*\(\s*AudioListener\s*\)|typeof\s*\(\s*AudioListener\s*\)/;
+export function listenerAdders(files) {
+    const out = new Set();
+    for (const f of files) {
+        if (!CODE_LISTENER.test(f.code))
+            continue;
+        const methods = methodsOf(f.code);
+        const direct = new Set();
+        for (const m of f.code.matchAll(new RegExp(CODE_LISTENER.source, 'g'))) {
+            const at = methodAt(methods, m.index);
+            if (at)
+                direct.add(at.name);
+        }
+        for (const m of methods) {
+            const body = f.code.slice(m.start, m.end);
+            if (direct.has(m.name) || [...direct].some((d) => new RegExp(`\\b${d}\\s*\\(`).test(body)))
+                out.add(`${m.cls}.${m.name}`);
+        }
+    }
+    return [...out];
+}
+const readText = (p, max = 32 * 1024 * 1024) => {
+    try {
+        return statSync(p).size > max ? '' : readFileSync(p, 'utf8');
+    }
+    catch {
+        return '';
+    }
+};
+export function checkAudioListener(p) {
+    const scenes = p.scenes.map((rel) => ({ rel, text: readText(join(p.dir, rel)) }));
+    const sceneCams = scenes.filter((s) => SCENE_CAMERA.test(s.text));
+    const codeCams = p.code.filter((f) => runtime(f) && CODE_CAMERA.test(f.code)).map((f) => f.rel);
+    if (!sceneCams.length && !codeCams.length)
+        return [];
+    const sceneHears = scenes.some((s) => SCENE_LISTENER.test(s.text));
+    const own = p.code.filter((f) => runtime(f) && CODE_LISTENER.test(f.code)).map((f) => f.rel);
+    const adders = listenerAdders(p.packageCode);
+    const called = adders.filter((a) => p.code.some((f) => runtime(f) && new RegExp(`\\b${a.replace('.', '\\s*\\.\\s*')}\\s*\\(`).test(f.code)));
+    if (own.length || called.length)
+        return [['pass', `AudioListener: added in code (${list([...own, ...called], 2)})`]];
+    const out = [];
+    for (const s of sceneCams) {
+        if (!SCENE_LISTENER.test(s.text))
+            out.push(['warn', `AudioListener: ${s.rel} has a camera and no AudioListener, and no code adds one — add one to its camera; with none the build plays no sound`]);
+    }
+    if (!sceneHears) {
+        for (const f of codeCams)
+            out.push(['warn', `AudioListener: ${f} makes a Camera in code and nothing adds an AudioListener — add one beside it (AddComponent<AudioListener>(), or Sfx.EnsureListener()); four of the studio's first games reached TestFlight silent`]);
+    }
+    return out.length ? out : [['pass', 'AudioListener: a scene has one']];
+}
+const OLD_INPUT = /(?<![\w.]|InputSystem\.)(?:UnityEngine\.)?Input\.(?:GetKey|GetKeyDown|GetKeyUp|GetAxis|GetAxisRaw|GetButton|GetButtonDown|GetButtonUp|GetMouseButton|GetMouseButtonDown|GetMouseButtonUp|GetTouch|touchCount|touches|mousePosition|mouseScrollDelta|anyKey|anyKeyDown|acceleration|inputString)\b/;
+export const BANNED_APIS = [
+    {
+        id: 'warmup-all-shaders',
+        api: 'Shader.WarmupAllShaders',
+        pattern: /\bShader\s*\.\s*WarmupAllShaders\s*\(/,
+        scope: 'runtime',
+        status: (p) => (usesUrp(p) ? 'fail' : 'warn'),
+        why: 'it segfaults with URP keyword spaces (Unity 6, two games) and compiles every variant of every shader',
+        fix: 'warm a ShaderVariantCollection of the variants the game draws with (ShaderVariantCollection.WarmUp)',
+    },
+    {
+        id: 'old-input-api',
+        api: 'UnityEngine.Input',
+        pattern: OLD_INPUT,
+        scope: 'runtime',
+        when: (p) => scalar(p.settings, 'activeInputHandler') === '1',
+        status: () => 'fail',
+        why: 'activeInputHandler is 1 (the Input System only), so every UnityEngine.Input call throws InvalidOperationException',
+        fix: 'read the Input System (Keyboard.current, Touchscreen.current, Mouse.current), or set Active Input Handling to Both',
+    },
+    {
+        id: 'input-at-assemblies-loaded',
+        api: 'RuntimeInitializeLoadType.AfterAssembliesLoaded with the Input System',
+        pattern: /RuntimeInitializeLoadType\s*\.\s*AfterAssembliesLoaded[\s\S]*\bInputSystem\b|\bInputSystem\b[\s\S]*RuntimeInitializeLoadType\s*\.\s*AfterAssembliesLoaded/,
+        scope: 'runtime',
+        status: () => 'warn',
+        why: 'the Input System is not up at AfterAssembliesLoaded on iOS: hooking it there throws, and every input read after it throws too',
+        fix: 'hook input on first use or at BeforeSceneLoad (a back-button reader that hooks on first read)',
+    },
+    {
+        id: 'bare-render-params',
+        api: 'new RenderParams{} / new RenderParams()',
+        pattern: /\bnew\s+RenderParams\s*(?:\{|\(\s*\))/,
+        scope: 'runtime',
+        status: () => 'warn',
+        why: 'a RenderParams with no material culls every RenderMeshPrimitives draw',
+        fix: 'new RenderParams(material)',
+    },
+    {
+        id: 'runtime-msaa',
+        api: 'QualitySettings.antiAliasing =',
+        pattern: /\bQualitySettings\s*\.\s*antiAliasing\s*=(?!=)/,
+        scope: 'runtime',
+        status: () => 'warn',
+        why: 'changing MSAA at runtime recompiles every pipeline state: a 1.5 s frame',
+        fix: 'set it once per quality tier in the project, or behind a loading screen',
+    },
+    {
+        id: 'word-wrapping',
+        api: 'enableWordWrapping',
+        pattern: /\.\s*enableWordWrapping\b/,
+        scope: 'cs',
+        when: (p) => major(p.version) >= 6000,
+        status: () => 'warn',
+        why: 'it is obsolete in Unity 6',
+        fix: 'textWrappingMode = TextWrappingModes.Normal (or NoWrap)',
+    },
+    {
+        id: 'batch-tmp-import',
+        api: 'ImportPackage of TMP Essential Resources',
+        pattern: /ImportPackage[\s\S]{0,200}TMP Essential Resources|TMP Essential Resources[\s\S]{0,200}ImportPackage|-importPackage[^\n]*TMP Essential/i,
+        scope: 'cs-strings-and-script',
+        status: (p) => (p.tmpSettings.length ? 'note' : 'warn'),
+        why: 'importing TMP Essential Resources in batch mode hangs',
+        fix: 'import them once in the Editor (Window > TextMeshPro > Import TMP Essential Resources) and commit them',
+    },
+    {
+        id: 'quit-with-run-tests',
+        api: '-quit with -runTests',
+        pattern: /^(?=.*-runTests\b)(?=.*-quit\b).*$/m,
+        scope: 'script',
+        status: () => 'warn',
+        why: 'the test runner exits Unity itself when the run ends, and -quit can end it before the tests run',
+        fix: 'drop -quit from the -runTests line',
+    },
+];
+const joinContinuations = (text) => text.replace(/\\\r?\n/g, ' ');
+export function lintApis(p) {
+    const out = [];
+    for (const row of BANNED_APIS) {
+        if (row.when && !row.when(p))
+            continue;
+        const scripts = row.scope === 'script' || row.scope === 'cs-strings-and-script' ? p.scripts.filter((s) => row.pattern.test(joinContinuations(s.text))).map((s) => s.rel) : [];
+        const cs = row.scope === 'script' ? [] : p.code.filter((f) => (row.scope !== 'runtime' || runtime(f)) && row.pattern.test(row.scope === 'cs-strings-and-script' ? f.withStrings : f.code)).map((f) => f.rel);
+        const hits = [...cs, ...scripts];
+        if (hits.length)
+            out.push([row.status(p), `${row.api} in ${list(hits)}: ${row.why} — ${row.fix}`]);
+    }
+    if (!out.length)
+        out.push(['pass', `no banned Unity API calls (${BANNED_APIS.length} looked for)`]);
+    return out;
+}
+export function checkShaderFind(p) {
+    const finds = new Map();
+    for (const f of p.code) {
+        if (!runtime(f))
+            continue;
+        for (const m of f.withStrings.matchAll(/\bShader\s*\.\s*Find\s*\(\s*"([^"]+)"\s*\)/g))
+            finds.set(m[1], [...(finds.get(m[1]) ?? []), f.rel]);
+    }
+    if (!finds.size || !p.shaders.length)
+        return [];
+    const own = new Map();
+    for (const rel of p.shaders) {
+        const name = /^\s*Shader\s+"([^"]+)"/m.exec(readText(join(p.dir, rel)))?.[1];
+        if (name && finds.has(name))
+            own.set(name, { rel, guid: /^guid:\s*([0-9a-f]{32})/m.exec(readText(join(p.dir, `${rel}.meta`)))?.[1] ?? null });
+    }
+    if (!own.size)
+        return [];
+    const unresolved = new Map([...own].filter(([, s]) => !s.rel.split(/[\\/]/).includes('Resources') && s.guid && !p.graphics.includes(s.guid)));
+    if (unresolved.size) {
+        for (const rel of p.referrers) {
+            const text = readText(join(p.dir, rel), 16 * 1024 * 1024);
+            for (const [name, s] of unresolved)
+                if (text.includes(s.guid))
+                    unresolved.delete(name);
+            if (!unresolved.size)
+                break;
+        }
+    }
+    const out = [];
+    for (const [name, s] of unresolved) {
+        out.push(['warn', `Shader.Find("${name}") in ${list([...new Set(finds.get(name))], 2)}: ${s.rel} is referenced by no material, Resources folder or Always Included Shaders, so the build strips it and Shader.Find returns null — add it to Project Settings > Graphics > Always Included Shaders, or reference it from a material`]);
+    }
+    return out;
+}
+export const GLTF_DECODERS = {
+    EXT_meshopt_compression: { packages: ['com.unity.meshopt.decompress'], what: 'meshopt geometry' },
+    KHR_draco_mesh_compression: { packages: ['com.unity.cloud.draco', 'com.atteneder.draco'], what: 'Draco geometry' },
+    KHR_texture_basisu: { packages: ['com.unity.cloud.ktx', 'com.atteneder.ktx'], what: 'Basis (KTX2) textures' },
+    EXT_texture_webp: { packages: null, what: 'WebP textures' },
+};
+export function gltfExtensions(path) {
+    let json;
+    try {
+        if (/\.gltf$/i.test(path))
+            json = statSync(path).size > 64 * 1024 * 1024 ? '' : readFileSync(path, 'utf8');
+        else {
+            const head = Buffer.alloc(20);
+            const fd = openSync(path, 'r');
+            try {
+                if (readSync(fd, head, 0, 20, 0) < 20 || head.toString('latin1', 0, 4) !== 'glTF' || head.toString('latin1', 16, 20) !== 'JSON')
+                    return null;
+                const len = head.readUInt32LE(12);
+                if (len > 64 * 1024 * 1024)
+                    return null;
+                const body = Buffer.alloc(len);
+                readSync(fd, body, 0, len, 20);
+                json = body.toString('utf8');
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        const g = JSON.parse(json);
+        return { used: g.extensionsUsed ?? [], required: g.extensionsRequired ?? [] };
+    }
+    catch {
+        return null;
+    }
+}
+export const GLB_FIX = 'decode it before Unity sees it (gltf-transform, skill funpixel-3d, its Unity page) or bring the engine\'s own GLB (`funtools gen model3d --raw`)';
+export function checkModels(p) {
+    if (!p.models.length)
+        return [];
+    const gltfast = p.manifest['com.unity.cloud.gltfast'] ?? p.manifest['com.atteneder.gltfast'];
+    if (!gltfast)
+        return [['warn', `${p.models.length} glTF/GLB file(s) under Assets (${list(p.models, 2)}) and no glTFast in Packages/manifest.json — Unity imports them only through it: add com.unity.cloud.gltfast (the studio pins 6.20.0)`]];
+    const blocked = new Map();
+    for (const rel of p.models) {
+        const ext = gltfExtensions(join(p.dir, rel));
+        if (!ext)
+            continue;
+        for (const e of new Set([...ext.used, ...ext.required])) {
+            const d = GLTF_DECODERS[e];
+            if (!d || (d.packages && d.packages.some((pkg) => p.manifest[pkg])))
+                continue;
+            const b = blocked.get(e) ?? { required: [], used: [] };
+            (ext.required.includes(e) ? b.required : b.used).push(rel);
+            blocked.set(e, b);
+        }
+    }
+    if (!blocked.size)
+        return [['pass', `${p.models.length} glTF/GLB file(s): nothing glTFast ${gltfast} cannot decode`]];
+    const out = [];
+    const fails = [];
+    for (const [e, b] of blocked) {
+        const d = GLTF_DECODERS[e];
+        const can = d.packages ? `glTFast ${gltfast} decodes it only with ${d.packages[0]}, which is not installed` : `glTFast ${gltfast} has no decoder for it`;
+        if (b.required.length)
+            fails.push(['fail', `${b.required.length} model(s) need ${e} (${d.what}): ${list(b.required, 2)} — ${can}, so they import as nothing, silently; ${GLB_FIX}`]);
+        if (b.used.length)
+            out.push(['warn', `${b.used.length} model(s) use ${e} (${d.what}) with a fallback: ${list(b.used, 2)} — ${can}; check they draw, or ${GLB_FIX}`]);
+    }
+    return [...fails, ...out];
+}
+const WRITES_PLAYER_SETTINGS = /\bPlayerSettings(?:\s*\.\s*\w+)*\s*\.\s*(?:\w+\s*=(?!=)|Set\w+\s*\()/g;
+const WRITES_ONE = new RegExp(WRITES_PLAYER_SETTINGS.source);
+const ORIENTATION = { Portrait: '0', PortraitUpsideDown: '1', LandscapeRight: '2', LandscapeLeft: '3', AutoRotation: '4' };
+const BACKEND_KEY = { iOS: 'iPhone', Android: 'Android', Standalone: 'Standalone' };
+const GRAPHICS_KEY = { iOS: 'iOSSupport', Android: 'AndroidPlayer' };
+export function pinsOf(code) {
+    const pins = [];
+    for (const m of code.matchAll(/\bPlayerSettings\s*\.\s*(?:SetUseDefaultGraphicsAPIs\s*\(\s*BuildTarget\s*\.\s*(iOS|Android)\s*,\s*false\s*\)|SetGraphicsAPIs\s*\(\s*BuildTarget\s*\.\s*(iOS|Android)\b)/g)) {
+        const t = m[1] ?? m[2];
+        pins.push({
+            setting: `${t} graphics APIs`,
+            wants: `a fixed list (${m[1] ? `SetUseDefaultGraphicsAPIs(${t}, false)` : `SetGraphicsAPIs(${t}, …)`})`,
+            same: 'a fixed list',
+            differs: (s) => (graphicsApis(s)[GRAPHICS_KEY[t]]?.automatic ?? true ? 'automatic' : null),
+        });
+    }
+    for (const m of code.matchAll(/\bPlayerSettings\s*\.\s*colorSpace\s*=\s*ColorSpace\s*\.\s*(Linear|Gamma)\s*;/g)) {
+        const want = m[1] === 'Linear' ? '1' : '0';
+        pins.push({ setting: 'colour space', wants: m[1], differs: (s) => { const v = scalar(s, 'm_ActiveColorSpace'); return v !== null && v !== want ? (v === '1' ? 'Linear' : 'Gamma') : null; } });
+    }
+    for (const m of code.matchAll(/\bPlayerSettings\s*\.\s*SetScriptingBackend\s*\(\s*(?:UnityEditor\s*\.\s*Build\s*\.\s*)?(?:NamedBuildTarget|BuildTargetGroup)\s*\.\s*(iOS|Android|Standalone)\s*,\s*ScriptingImplementation\s*\.\s*(IL2CPP|Mono2x)\s*\)/g)) {
+        const key = BACKEND_KEY[m[1]];
+        const want = m[2] === 'IL2CPP' ? '1' : '0';
+        pins.push({ setting: `${m[1]} scripting backend`, wants: m[2], differs: (s) => { const v = yamlMap(s, 'scriptingBackend')[key]; return v !== undefined && v !== want ? (v === '1' ? 'IL2CPP' : 'Mono') : null; } });
+    }
+    for (const m of code.matchAll(/\bPlayerSettings\s*\.\s*iOS\s*\.\s*targetOSVersionString\s*=\s*"([\d.]+)"\s*;/g)) {
+        pins.push({ setting: 'iOS minimum version', wants: m[1], differs: (s) => { const v = scalar(s, 'iOSTargetOSVersionString'); return v !== null && v !== m[1] ? v : null; } });
+    }
+    for (const m of code.matchAll(/\bPlayerSettings\s*\.\s*defaultInterfaceOrientation\s*=\s*UIOrientation\s*\.\s*(\w+)\s*;/g)) {
+        const want = ORIENTATION[m[1]];
+        if (want === undefined)
+            continue;
+        pins.push({ setting: 'default orientation', wants: m[1], differs: (s) => { const v = scalar(s, 'defaultScreenOrientation'); return v !== null && v !== want ? Object.keys(ORIENTATION).find((k) => ORIENTATION[k] === v) ?? v : null; } });
+    }
+    for (const m of code.matchAll(/\bPlayerSettings\s*\.\s*accelerometerFrequency\s*=\s*(\d+)\s*;/g)) {
+        pins.push({ setting: 'accelerometer frequency', wants: m[1], differs: (s) => { const v = scalar(s, 'accelerometerFrequency'); return v !== null && v !== m[1] ? v : null; } });
+    }
+    return pins;
+}
+export function setupMethods(p) {
+    const fromPackages = new Map();
+    for (const f of p.packageCode.filter((x) => x.editor)) {
+        const methods = methodsOf(f.withStrings);
+        for (const m of methods) {
+            const body = f.withStrings.slice(m.start, m.end);
+            if (WRITES_ONE.test(body))
+                fromPackages.set(`${m.cls}.${m.name}`, body);
+        }
+    }
+    const found = new Map();
+    for (const f of p.code.filter((x) => x.editor)) {
+        const methods = methodsOf(f.withStrings);
+        for (const m of methods) {
+            const body = f.withStrings.slice(m.start, m.end);
+            const writes = [...body.matchAll(WRITES_PLAYER_SETTINGS)].length;
+            const calls = [...fromPackages.keys()].filter((k) => new RegExp(`\\b${k.replace('.', '\\s*\\.\\s*')}\\s*\\(`).test(body));
+            if (!writes && !calls.length)
+                continue;
+            const name = `${m.cls}.${m.name}`;
+            const prev = found.get(name);
+            found.set(name, { name, writes: (prev?.writes ?? 0) + writes + calls.length, code: (prev?.code ?? '') + body + calls.map((c) => fromPackages.get(c)).join('\n') });
+        }
+    }
+    const named = (m) => { const [cls, fn] = m.name.split('.'); return (/^(configure|setup|apply)/i.test(fn) ? 2 : 0) + (/setup|config/i.test(cls) ? 1 : 0); };
+    return [...found.values()].sort((a, b) => named(b) - named(a) || b.writes - a.writes || a.name.localeCompare(b.name));
+}
+export function checkSettingsDrift(p) {
+    const methods = setupMethods(p);
+    if (!methods.length || !p.settings)
+        return [];
+    const main = methods[0].name;
+    const others = methods.length > 1 ? ` (and ${methods.length - 1} other setup method${methods.length > 2 ? 's' : ''})` : '';
+    const pins = new Map();
+    for (const m of methods)
+        for (const pin of pinsOf(m.code))
+            pins.set(pin.setting, [...(pins.get(pin.setting) ?? []), pin]);
+    const drift = [];
+    let compared = 0;
+    for (const [setting, list] of pins) {
+        if (new Set(list.map((x) => x.same ?? x.wants)).size > 1)
+            continue;
+        compared++;
+        const now = list[0].differs(p.settings);
+        if (now)
+            drift.push(`${setting} saved as ${now}, the script pins ${list[0].wants}`);
+    }
+    if (drift.length) {
+        return [['warn', `settings drift: ProjectSettings.asset disagrees with ${main}${others}: ${drift.join('; ')} — run ${main} before every build (a build that skips it ships what the Editor last saved; one game's iOS graphics APIs flipped back to automatic three times)`]];
+    }
+    return [['pass', `settings: ${main}${others} sets PlayerSettings${compared ? `, and the saved ones agree (${compared} compared)` : ''} — build through it every time`]];
+}
+export function projectChecks(p) {
+    return [...checkInput(p), ...checkTmp(p), ...checkAudioListener(p), ...lintApis(p), ...checkShaderFind(p), ...checkModels(p), ...checkSettingsDrift(p)];
+}