ravensight-playtest 0.5.2 → 0.6.0

package/src/assets/integration.js

@@ -0,0 +1,429 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  checkEnv, copyForCheck, CHECK_TIMEOUTS_MS, detectSandbox, parseGodotErrors, runBounded, sandboxProfile, testFileRefusal, toolScriptRefusal
+} from '../run/checks.js';
+import { detectGodotBinary } from '../run/drivers/godot-project.js';
+import { listFiles } from '../run/repoTools.js';
+import { defaultFilter, isMediaPath } from './inventory.js';
+
+/**
+ * Whether the art and audio a change names actually work: three named checks in
+ * the run_check set, plus the scan that says which files a project uses.
+ *
+ * - `asset_references` reads the changed files: every asset they name exists, with
+ *   that exact case, inside the project. No process runs.
+ * - `asset_import` imports a temporary copy of the project in real Godot and reads
+ *   what it produced for each asset the change names.
+ * - `pixel_art_settings` reads settings: pixel art the change names is drawn with
+ *   the nearest filter, with no mipmaps and no lossy or VRAM compression.
+ *
+ * Only what the change names can fail. A studio's old unused file or an old broken
+ * reference is the studio's business, and no job is refunded because of it.
+ */
+
+export const ASSET_CHECK_NAMES = Object.freeze(['asset_references', 'asset_import', 'pixel_art_settings']);
+
+/** A failure here means the game breaks, so no change like it is uploaded. */
+export const BLOCKING_ASSET_CHECKS = Object.freeze(['asset_references', 'asset_import']);
+
+const TEXT_EXTENSIONS = Object.freeze(['.gd', '.tscn', '.tres', '.gdshader', '.cfg']);
+const MAX_SCANNED_BYTES = 4 * 1024 * 1024;
+const MAX_LISTED = 40;
+
+const RESOURCE = /(res|uid):\/\/[^"'\s)\]}]*/g;
+const LOADING_CALL = /\b(?:preload|load|load_from_file|load_threaded_request)\s*\(\s*["']([^"']+)["']/g;
+
+/** A script's text with its comments removed: a note about a future file is not a reference. */
+export function withoutComments(text) {
+  return String(text).split('\n').map(line => {
+    let quote = null;
+    for (let i = 0; i < line.length; i += 1) {
+      const char = line[i];
+      if (quote) {
+        if (char === '\\') i += 1;
+        else if (char === quote) quote = null;
+      } else if (char === '"' || char === "'") quote = char;
+      else if (char === '#') return line.slice(0, i);
+    }
+    return line;
+  }).join('\n');
+}
+
+/**
+ * Everything one text file names, sorted out.
+ *
+ * @param {string} text
+ * @param {string} file its name, which decides the comment rule
+ * @returns {{exact: string[], patterns: string[], prefixes: string[], uids: string[], loose: string[]}}
+ *   `exact` are project relative asset paths, `patterns` are paths with a format
+ *   marker in them, `prefixes` are folders a path is built from, and `loose` are
+ *   asset paths given to a loading call that are not `res://` paths at all
+ */
+export function scanReferences(text, file = 'x.gd') {
+  const source = file.endsWith('.gd') ? withoutComments(text) : String(text);
+  const out = { exact: new Set(), patterns: new Set(), prefixes: new Set(), uids: new Set(), loose: new Set() };
+  for (const match of source.matchAll(RESOURCE)) {
+    const value = match[0];
+    if (value.startsWith('uid://')) {
+      out.uids.add(value);
+      continue;
+    }
+    const relative = value.slice('res://'.length);
+    if (/%[-0-9.]*[a-z]|\{[^}]*\}/i.test(relative)) {
+      if (isMediaPath(relative.replace(/%[-0-9.]*[a-z]|\{[^}]*\}/gi, 'x'))) out.patterns.add(relative);
+    } else if (relative.endsWith('/')) out.prefixes.add(relative);
+    else if (isMediaPath(relative)) out.exact.add(path.posix.normalize(relative));
+  }
+  for (const match of source.matchAll(LOADING_CALL)) {
+    const value = match[1];
+    if (!/^(res|uid|user):\/\//.test(value) && isMediaPath(value)) out.loose.add(value);
+  }
+  return {
+    exact: [...out.exact], patterns: [...out.patterns], prefixes: [...out.prefixes], uids: [...out.uids], loose: [...out.loose]
+  };
+}
+
+/** A project file's text, or null. A link is not followed: it could lead out of the project. */
+async function readInside(projectDir, relative) {
+  const absolute = path.join(projectDir, relative);
+  const info = await fs.lstat(absolute).catch(() => null);
+  if (!info || !info.isFile() || info.size > MAX_SCANNED_BYTES) return null;
+  return fs.readFile(absolute, 'utf8').catch(() => null);
+}
+
+async function scanFile(projectDir, relative) {
+  const text = await readInside(projectDir, relative);
+  return text === null ? null : scanReferences(text, relative);
+}
+
+function isScanned(relative) {
+  return relative === 'project.godot' || TEXT_EXTENSIONS.includes(path.extname(relative).toLowerCase());
+}
+
+/**
+ * Whether a project relative path exists with exactly that case. A case-insensitive
+ * disk answers yes to the wrong case, and an exported game then cannot find it.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function existsExactly(projectDir, relative) {
+  let directory = projectDir;
+  const segments = relative.split('/').filter(Boolean);
+  for (const [index, segment] of segments.entries()) {
+    const names = await fs.readdir(directory).catch(() => []);
+    if (!names.includes(segment)) return false;
+    directory = path.join(directory, segment);
+    if (index === segments.length - 1) {
+      const info = await fs.lstat(directory).catch(() => null);
+      return Boolean(info && info.isFile());
+    }
+  }
+  return false;
+}
+
+/** A pattern from code, like `tiles/floor_%d.png`, as a test of a path. */
+function patternTest(pattern) {
+  const source = pattern.split(/%[-0-9.]*[a-z]|\{[^}]*\}/i).map(part => part.replace(/[.+^${}()|[\]\\]/g, '\\$&')).join('.*');
+  return new RegExp(`^${source}$`);
+}
+
+async function uidsOf(projectDir, files) {
+  const map = new Map();
+  for (const file of files) {
+    const text = await readInside(projectDir, `${file.path}.import`);
+    const match = text && /^uid="(uid:\/\/[^"]+)"/m.exec(text);
+    if (match) map.set(match[1], file.path);
+  }
+  return map;
+}
+
+/**
+ * Which of the inventory's files the project uses as it stands, and which of those
+ * the change named.
+ *
+ * @param {{projectDir: string, inventory: Object, changed: string[]}} input
+ * @returns {Promise<{used: string[], unused: string[], wired: string[], built_in_code: string[]}>}
+ */
+export async function scanUsage({ projectDir, inventory, changed = [] }) {
+  const names = inventory.files.map(file => file.path);
+  const uids = await uidsOf(projectDir, inventory.files);
+  const everywhere = (await listFiles(projectDir)).filter(isScanned);
+  const direct = new Set();
+  const built = new Set();
+  const wired = new Set();
+  const changedSet = new Set(changed.map(file => file.split(path.sep).join('/')));
+  for (const file of everywhere) {
+    const found = await scanFile(projectDir, file);
+    if (!found) continue;
+    const hits = new Set(found.exact.filter(item => names.includes(item)));
+    for (const uid of found.uids) if (uids.has(uid)) hits.add(uids.get(uid));
+    const shaped = new Set();
+    for (const pattern of found.patterns) {
+      const test = patternTest(pattern);
+      for (const name of names) if (test.test(name)) shaped.add(name);
+    }
+    for (const prefix of found.prefixes) for (const name of names) if (name.startsWith(prefix)) shaped.add(name);
+    for (const item of hits) direct.add(item);
+    for (const item of shaped) built.add(item);
+    if (changedSet.has(file)) {
+      for (const item of hits) wired.add(item);
+      for (const item of shaped) wired.add(item);
+    }
+  }
+  const used = names.filter(name => direct.has(name) || built.has(name));
+  return {
+    used,
+    unused: names.filter(name => !direct.has(name) && !built.has(name)),
+    wired: names.filter(name => wired.has(name)),
+    built_in_code: names.filter(name => built.has(name) && !direct.has(name))
+  };
+}
+
+function capped(items) {
+  return items.length > MAX_LISTED ? [...items.slice(0, MAX_LISTED), `and ${items.length - MAX_LISTED} more`] : items;
+}
+
+/** What the changed files name, with where each came from. */
+async function namedByChange(projectDir, changed, uidMap) {
+  const rows = [];
+  for (const file of changed.map(item => item.split(path.sep).join('/')).filter(isScanned)) {
+    const found = await scanFile(projectDir, file);
+    if (!found) continue;
+    for (const asset of found.exact) rows.push({ file, asset, kind: 'res' });
+    for (const uid of found.uids) if (uidMap.has(uid)) rows.push({ file, asset: uidMap.get(uid), kind: 'res' });
+    for (const asset of found.loose) rows.push({ file, asset, kind: 'loose' });
+  }
+  return rows;
+}
+
+function dedupe(rows) {
+  const seen = new Set();
+  return rows.filter(row => {
+    const key = `${row.kind}:${row.asset}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * The problem with each reference a change makes, as lines a repair can act on.
+ *
+ * @returns {Promise<string[]>}
+ */
+export async function referenceProblems({ projectDir, rows }) {
+  const problems = [];
+  for (const { file, asset, kind } of rows) {
+    if (kind === 'loose') {
+      problems.push(`${file} loads "${asset}", which is not a res:// path. Use the res_path from the manifest.`);
+    } else if (asset === '..' || asset.startsWith('../')) {
+      problems.push(`${file} names res://${asset}, which is outside the project.`);
+    } else if (!await existsExactly(projectDir, asset)) {
+      problems.push(`${file} names res://${asset}, and no file has exactly that path. Use a res_path from the manifest, or a placeholder primitive named in the plan's placeholders.`);
+    }
+  }
+  return problems;
+}
+
+const NEAREST_IN_SCRIPT = /TEXTURE_FILTER_NEAREST\b|texture_filter\s*=\s*1\b/;
+
+/** The import settings that spoil pixel art, from a `.import` file's text. */
+export function importSettingProblems(text) {
+  const problems = [];
+  const setting = name => {
+    const match = new RegExp(`^${name}=(.+)$`, 'm').exec(text);
+    return match ? match[1].trim() : null;
+  };
+  if (setting('mipmaps/generate') === 'true') problems.push('mipmaps are on');
+  const mode = setting('compress/mode');
+  if (mode !== null && mode !== '0') problems.push(`compress/mode is ${mode}, and pixel art needs 0 (lossless)`);
+  const limit = setting('process/size_limit');
+  if (limit !== null && limit !== '0') problems.push(`process/size_limit is ${limit}, which resizes the art`);
+  return problems;
+}
+
+/**
+ * The three checks, bound to one project and one inventory. Each result has the
+ * shape `createCheckRunner` gives, and goes into its `results`, so the evidence and
+ * the changeset carry them beside the others.
+ *
+ * @param {Object} args
+ * @param {string} args.projectDir
+ * @param {Object} args.inventory from buildInventory
+ * @param {{results: Array}} args.checks the run's `createCheckRunner` surface
+ * @param {() => Promise<string[]>} args.changedFiles project relative paths
+ * @param {string|null} [args.godotPath]
+ * @param {boolean} [args.allowToolScripts]
+ * @param {boolean} [args.allowTests]
+ * @returns {{run: (name: string) => Promise<Object>, gate: (gate: Object, log?: Function) => Promise<Object>}}
+ */
+export function createAssetChecks({
+  projectDir,
+  inventory,
+  checks,
+  changedFiles,
+  godotPath = null,
+  allowToolScripts = false,
+  allowTests = false,
+  env = process.env,
+  spawnFn,
+  detect = detectGodotBinary,
+  copy = copyForCheck,
+  sandbox = undefined,
+  platform = process.platform,
+  timeoutMs = CHECK_TIMEOUTS_MS.godot_import,
+  now = () => Date.now()
+}) {
+  let sandboxPath = sandbox;
+  const made = (name, started, status, detail, errors = [], output = '') => ({
+    name, status, ok: status === 'passed' ? true : (status === 'failed' || status === 'check_refused' ? false : null),
+    durationMs: now() - started, errors, detail, output
+  });
+  const fileOf = target => inventory.files.find(file => file.path === target);
+
+  async function rowsOf(changed) {
+    const uids = await uidsOf(projectDir, inventory.files);
+    return dedupe(await namedByChange(projectDir, changed, uids));
+  }
+
+  async function references(started) {
+    const rows = await rowsOf(await changedFiles());
+    if (rows.length === 0) return made('asset_references', started, 'passed', 'the change names no asset');
+    const problems = await referenceProblems({ projectDir, rows });
+    return problems.length > 0
+      ? made('asset_references', started, 'failed', `${problems.length} asset reference(s) do not resolve`, capped(problems))
+      : made('asset_references', started, 'passed', `${rows.length} asset(s) named, all present`);
+  }
+
+  async function importAssets(started) {
+    const changed = await changedFiles();
+    const rows = (await rowsOf(changed)).filter(row => row.kind === 'res');
+    const present = [];
+    for (const row of rows) if (await existsExactly(projectDir, row.asset)) present.push(row.asset);
+    if (present.length === 0) return made('asset_import', started, 'passed', 'the change names no asset to import');
+    const refusal = (allowToolScripts ? null : await toolScriptRefusal(projectDir, changed)) || (allowTests ? null : await testFileRefusal(projectDir, changed));
+    if (refusal) return made('asset_import', started, 'check_refused', refusal);
+    let binary = null;
+    try {
+      binary = (await detect({ explicitPath: godotPath || undefined, projectDir, env })).path;
+    } catch {
+      binary = null;
+    }
+    if (!binary) return made('asset_import', started, 'unavailable', 'no Godot 4.2+ binary was found; pass --godot-path or set RAVENSIGHT_GODOT');
+    let copied;
+    try {
+      copied = await copy(projectDir);
+    } catch (error) {
+      return made('asset_import', started, 'failed', `the project could not be copied: ${error.message}`);
+    }
+    try {
+      if (sandboxPath === undefined) sandboxPath = await detectSandbox({ platform });
+      const environment = checkEnv({ root: copied.root, env, platform });
+      await Promise.all(['HOME', 'TMPDIR', 'XDG_DATA_HOME', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'APPDATA', 'LOCALAPPDATA']
+        .filter(key => environment[key]).map(key => fs.mkdir(environment[key], { recursive: true })));
+      const args = ['--headless', '--path', copied.copy, '--import'];
+      const options = { cwd: copied.copy, env: environment, timeoutMs, ...(spawnFn ? { spawnFn } : {}) };
+      const real = await fs.realpath(copied.root).catch(() => copied.root);
+      const imported = sandboxPath
+        ? await runBounded(sandboxPath, ['-p', sandboxProfile([copied.root, real]), binary, ...args], options)
+        : await runBounded(binary, args, options);
+      if (imported.error) return made('asset_import', started, 'failed', imported.error, [], imported.output);
+      const problems = [];
+      const log = String(imported.output || '');
+      for (const asset of present) {
+        const text = await fs.readFile(path.join(copied.copy, `${asset}.import`), 'utf8').catch(() => null);
+        if (text === null) {
+          problems.push(`Godot did not import ${asset}. Godot has no importer for this file, or it is damaged.`);
+          continue;
+        }
+        if (/^valid=false/m.test(text)) {
+          problems.push(`Godot could not import ${asset}.`);
+          continue;
+        }
+        const targets = /^dest_files=\[(.*)\]$/m.exec(text);
+        const outputs = targets ? [...targets[1].matchAll(/"res:\/\/([^"]+)"/g)].map(match => match[1]) : [];
+        if (outputs.length === 0) {
+          problems.push(`Godot produced nothing for ${asset}.`);
+          continue;
+        }
+        for (const output of outputs) {
+          if (!await fs.stat(path.join(copied.copy, output)).catch(() => null)) problems.push(`Godot did not finish importing ${asset}.`);
+        }
+        if (log.split('\n').some(line => /^(ERROR|SCRIPT ERROR)/.test(line.trim()) && line.includes(asset))) problems.push(`Godot reported an error about ${asset}.`);
+      }
+      const scriptErrors = parseGodotErrors(log);
+      return problems.length > 0
+        ? made('asset_import', started, 'failed', `${problems.length} asset(s) did not import`, capped(problems), log)
+        : made('asset_import', started, 'passed', `${present.length} asset(s) imported${scriptErrors.length ? `; the import also listed ${scriptErrors.length} script error(s), which godot_import reports` : ''}`);
+    } finally {
+      await fs.rm(copied.root, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  async function pixelArt(started) {
+    const changed = await changedFiles();
+    const rows = (await rowsOf(changed)).filter(row => row.kind === 'res');
+    const pixelRows = rows.filter(row => fileOf(row.asset)?.image?.pixel_art);
+    if (pixelRows.length === 0) return made('pixel_art_settings', started, 'passed', 'the change names no pixel art');
+    const settings = (await readInside(projectDir, 'project.godot')) || '';
+    const nearestByDefault = defaultFilter(settings) === 'nearest';
+    const problems = [];
+    for (const { file, asset } of pixelRows) {
+      if (!nearestByDefault) {
+        const text = (await readInside(projectDir, file)) || '';
+        const source = file.endsWith('.gd') ? withoutComments(text) : text;
+        if (!NEAREST_IN_SCRIPT.test(source)) {
+          problems.push(`${file} draws ${asset}, which is pixel art, and the project's default filter is smooth, so it blurs. Set texture_filter = CanvasItem.TEXTURE_FILTER_NEAREST on the node that draws it${file.endsWith('.tscn') ? ' (texture_filter = 1 in a scene)' : ''}.`);
+        }
+      }
+      const imported = await readInside(projectDir, `${asset}.import`);
+      if (imported !== null) {
+        for (const problem of importSettingProblems(imported)) problems.push(`${asset}.import: ${problem}.`);
+      }
+    }
+    return problems.length > 0
+      ? made('pixel_art_settings', started, 'failed', `${problems.length} pixel art setting(s) are wrong`, capped(problems))
+      : made('pixel_art_settings', started, 'passed', `${pixelRows.length} pixel art asset(s) set up right`);
+  }
+
+  async function run(name) {
+    const started = now();
+    let result;
+    try {
+      if (name === 'asset_references') result = await references(started);
+      else if (name === 'asset_import') result = await importAssets(started);
+      else if (name === 'pixel_art_settings') result = await pixelArt(started);
+      else result = made(String(name), started, 'refused', `there is no check called ${name}`);
+    } catch (error) {
+      result = made(String(name), started, 'failed', `the check broke: ${error.message}`);
+    }
+    if (checks && Array.isArray(checks.results)) checks.results.push(result);
+    return result;
+  }
+
+  /**
+   * The asset checks, after the ordinary gate. Answers the same gate with any
+   * failures added, and `assetsBlock` when the change breaks the game outright.
+   */
+  async function gate(ordinary, log = () => {}) {
+    const failed = [...ordinary.failed];
+    let assetsBlock = false;
+    for (const name of ASSET_CHECK_NAMES) {
+      // A failed or refused import has already said the project cannot be imported.
+      if (name === 'asset_import' && ordinary.importFailed) continue;
+      const result = await run(name);
+      log(`check ${name}: ${result.status} (${result.detail})`);
+      if (result.status === 'failed' || result.status === 'check_refused') {
+        failed.push(result);
+        if (BLOCKING_ASSET_CHECKS.includes(name)) assetsBlock = true;
+      }
+    }
+    return { ...ordinary, failed, assetsBlock };
+  }
+
+  return { run, gate };
+}
+
+export default { createAssetChecks, scanUsage, scanReferences, ASSET_CHECK_NAMES, BLOCKING_ASSET_CHECKS };