vimp-engine 0.8.0 → 0.10.0

package/src/devtools/contract/rules/a1-package-fields.js

@@ -0,0 +1,81 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Поля package.json, от которых зависит не сборка, а поведение в бою:
+// вбандленный pixi.js даёт вторую копию PixiJS со своим реестром расширений
+// (объекты одной копии падают в другой), а vimp-engine в dependencies тянет
+// движок внутрь пакета игры — движок загружает плагин, не наоборот.
+export default {
+  id: 'A1',
+  name: 'packageFields',
+  level: ERROR,
+  title: 'package.json: type, files, pixi.js, vimp-engine, publishConfig',
+
+  check(ctx) {
+    if (!ctx.pkg) {
+      return skip('no package.json');
+    }
+
+    const {
+      name,
+      type,
+      files,
+      publishConfig,
+      dependencies = {},
+      devDependencies = {},
+      peerDependencies = {},
+    } = ctx.pkg;
+    const violations = [];
+
+    if (type !== 'module') {
+      violations.push(`"type" is ${JSON.stringify(type)}, must be "module"`);
+    }
+
+    // npm принимает запись каталога в трёх видах ("dist", "dist/",
+    // "./dist") — сравнение строкой отвергало бы две из трёх
+    if (!Array.isArray(files) || !files.some(isDistEntry)) {
+      violations.push('"files" must list "dist" — only dist/ is published');
+    }
+
+    if (dependencies['pixi.js']) {
+      violations.push(
+        'pixi.js is in dependencies — it must be external (peer + dev), ' +
+          'otherwise the bundle ships a second PixiJS instance',
+      );
+    }
+
+    if (!peerDependencies['pixi.js']) {
+      violations.push('pixi.js is missing from peerDependencies');
+    }
+
+    if (!devDependencies['pixi.js']) {
+      violations.push(
+        'pixi.js is missing from devDependencies — the build needs it locally',
+      );
+    }
+
+    if (dependencies['vimp-engine']) {
+      violations.push(
+        'vimp-engine is in dependencies — it belongs in devDependencies',
+      );
+    }
+
+    if (!devDependencies['vimp-engine']) {
+      violations.push('vimp-engine is missing from devDependencies');
+    }
+
+    if (name?.startsWith('@') && publishConfig?.access !== 'public') {
+      violations.push(
+        `scoped package "${name}" needs publishConfig.access: "public"`,
+      );
+    }
+
+    return verdict(violations);
+  },
+};
+
+function isDistEntry(entry) {
+  return (
+    typeof entry === 'string' &&
+    entry.replace(/^\.\//, '').replace(/\/+$/, '') === 'dist'
+  );
+}

package/src/devtools/contract/rules/a2-package-scripts.js

@@ -0,0 +1,36 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Набор npm-скриптов пакета игры (docs/ai/02-packaging.md). Это не вкусовое
+// требование: инструкции движка и CI сгенерированной игры зовут их по имени,
+// а отсутствующий core:build:node тихо оставляет headless-прогон без ядра.
+const REQUIRED = [
+  'build',
+  'build:client',
+  'build:host',
+  'build:assets',
+  'build:manifest',
+  'core:build:web',
+  'core:build:node',
+  'core:test',
+  'test',
+];
+
+export default {
+  id: 'A2',
+  name: 'packageScripts',
+  level: ERROR,
+  title: 'package.json declares the standard build/test scripts',
+
+  check(ctx) {
+    if (!ctx.pkg) {
+      return skip('no package.json');
+    }
+
+    const scripts = ctx.pkg.scripts ?? {};
+    const missing = REQUIRED.filter(name => !scripts[name]);
+
+    return verdict(
+      missing.map(name => `script "${name}" is missing`),
+    );
+  },
+};

package/src/devtools/contract/rules/a3-entry-paths.js

@@ -0,0 +1,30 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Пути точек входа захардкожены в dev-режиме мастера
+// (GameCatalog._toDevManifest отдаёт браузеру /@fs/<пакет>/src/client/index.js).
+// Игра, разложившая половины иначе, собирается и публикуется нормально, а в
+// dev-режиме просто не грузится.
+export default {
+  id: 'A3',
+  name: 'entryPaths',
+  level: ERROR,
+  title: 'entries live at src/client/index.js and src/host/index.js',
+
+  check(ctx) {
+    if (!ctx.pkg) {
+      return skip('no package.json');
+    }
+
+    const violations = [];
+
+    if (!ctx.hostEntryExists) {
+      violations.push('src/host/index.js is missing — dev mode hardcodes it');
+    }
+
+    if (!ctx.clientEntryExists) {
+      violations.push('src/client/index.js is missing — dev mode hardcodes it');
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/a4-vite-config.js

@@ -0,0 +1,47 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// vite.config.js проверяется как текст, а не импортом: конфиг —
+// функция от mode и вне Vite не исполняется. Каждый пункт здесь ловит
+// молчаливую поломку сборки, а не стилистику (docs/ai/02-packaging.md):
+// без preserveEntrySignatures default-экспорт плагина вытряхивает
+// tree-shaking, а build.lib всегда инлайнит ассеты.
+const REQUIRED = [
+  [/emptyOutDir\s*:\s*false/, 'emptyOutDir: false (two builds share dist/)'],
+  [/assetsInlineLimit\s*:\s*0/, 'assetsInlineLimit: 0'],
+  [
+    /preserveEntrySignatures\s*:\s*['"]strict['"]/,
+    "preserveEntrySignatures: 'strict' (or the default export is tree-shaken)",
+  ],
+  [/inlineDynamicImports\s*:\s*true/, 'inlineDynamicImports: true'],
+  // external записывают и строкой, и регэкспом (/^pixi\.js(\/.*)?$/), а в
+  // регэкспе встречается ']' — ограничиваем не символом, а длиной хвоста
+  [/external\s*:\s*\[[\s\S]{0,400}?pixi/, 'external with pixi.js'],
+  [/entryFileNames[^\n]*\[hash\]/, 'entryFileNames with [hash]'],
+];
+
+export default {
+  id: 'A4',
+  name: 'viteConfig',
+  level: ERROR,
+  title: 'vite.config.js carries the required rollup options',
+
+  check(ctx) {
+    if (!ctx.viteText) {
+      return skip('no vite.config.js');
+    }
+
+    const violations = REQUIRED.filter(([re]) => !re.test(ctx.viteText)).map(
+      ([, what]) => `vite.config.js: missing ${what}`,
+    );
+
+    // именно build.lib: ключ `lib` встречается и в resolve.alias, и в
+    // именах путей — без привязки к build это ложный отказ
+    if (/build\s*:\s*\{[\s\S]{0,400}?\blib\s*:\s*[{'"]/.test(ctx.viteText)) {
+      violations.push(
+        'vite.config.js: build.lib is used — it always inlines assets',
+      );
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/a5-cargo-core.js

@@ -0,0 +1,194 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// core/Cargo.toml. Три пункта, каждый — молчаливый отказ:
+// crate-type без cdylib не даёт .wasm, rapier2d без enhanced-determinism
+// разъезжается между хостом и предиктором на разных машинах, а устаревший
+// пин vimp-engine-core собирает игру с чужим ABI (болезнь vimp-street-fighters:
+// пин 0.1.0 при крейте движка 0.3.2).
+export default {
+  id: 'A5',
+  name: 'cargoCore',
+  level: ERROR,
+  title: 'core/Cargo.toml: crate-type, rapier2d determinism, engine pin',
+
+  check(ctx) {
+    if (!ctx.cargoText) {
+      return skip('no core/Cargo.toml');
+    }
+
+    const violations = [];
+    // именно в [lib]: тот же ключ встречается в комментариях и в чужих
+    // секциях, и поиск по всему файлу выдал бы за проверку случайную строку
+    const crateType = readSection(ctx.cargoText, 'lib')?.match(
+      /^\s*crate-type\s*=\s*\[([^\]]*)\]/m,
+    )?.[1];
+
+    if (!crateType) {
+      violations.push('[lib] crate-type is missing (need ["cdylib", "rlib"])');
+    } else {
+      for (const kind of ['cdylib', 'rlib']) {
+        if (!crateType.includes(kind)) {
+          violations.push(`[lib] crate-type does not list "${kind}"`);
+        }
+      }
+    }
+
+    const rapier = resolveDep(ctx, 'rapier2d');
+
+    if (!rapier.declared) {
+      violations.push('rapier2d is not a dependency');
+    } else if (rapier.text && !rapier.text.includes('enhanced-determinism')) {
+      violations.push(
+        'rapier2d is missing the "enhanced-determinism" feature — physics ' +
+          'diverges between machines',
+      );
+    }
+
+    violations.push(...checkEnginePin(ctx));
+
+    return verdict(violations);
+  },
+};
+
+// зависимость крейта: `{ workspace = true }` уводит за реальным
+// объявлением в корневой Cargo.toml — там же живут и версия, и фичи.
+// Недостижимый корень — не нарушение, а отсутствие входа: возвращаем
+// null и объявляем зависимость непроверяемой (declared остаётся true)
+function resolveDep(ctx, name) {
+  const declaration = readDep(ctx.cargoText, name);
+
+  if (!declaration) {
+    return { declared: false, text: null };
+  }
+
+  if (/workspace\s*=\s*true/.test(declaration)) {
+    return {
+      declared: true,
+      text: ctx.workspaceCargoText
+        ? readDep(ctx.workspaceCargoText, name)
+        : null,
+    };
+  }
+
+  return { declared: true, text: declaration };
+}
+
+function checkEnginePin(ctx) {
+  const { declared, text } = resolveDep(ctx, 'vimp-engine-core');
+
+  if (!declared) {
+    return ['vimp-engine-core is not a dependency'];
+  }
+
+  // отсутствие входа не должно выглядеть зелёной галочкой: остальные
+  // пункты A5 проверены, а пин — нет, и это обязано быть в отчёте
+  if (!ctx.engineCoreVersion) {
+    ctx.notes?.push(
+      'A5: the engine crate version is unknown — the vimp-engine-core pin ' +
+        'was NOT checked',
+    );
+
+    return [];
+  }
+
+  if (!text) {
+    ctx.notes?.push(
+      'A5: the vimp-engine-core declaration was not found in [dependencies] ' +
+        '/ [workspace.dependencies] — the pin was NOT checked',
+    );
+
+    return [];
+  }
+
+  const pinned = text.match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+
+  if (!pinned) {
+    ctx.notes?.push(
+      `A5: vimp-engine-core is declared without a version (${text.trim()}) — ` +
+        'the pin was NOT checked',
+    );
+
+    return [];
+  }
+
+  const engine = ctx.engineCoreVersion.split('.').map(Number);
+  const game = [Number(pinned[1]), Number(pinned[2])];
+  const order = game[0] - engine[0] || game[1] - engine[1];
+
+  if (order < 0) {
+    return [
+      `vimp-engine-core is pinned to ${game.join('.')}, older than this ` +
+        `engine's crate ${ctx.engineCoreVersion}`,
+    ];
+  }
+
+  if (order > 0) {
+    return [
+      `vimp-engine-core is pinned to ${game.join('.')}, ahead of this ` +
+        `engine's crate ${ctx.engineCoreVersion}`,
+    ];
+  }
+
+  return [];
+}
+
+// секции, в которых объявление зависимости считается объявлением. Поиск
+// по всему файлу ловил бы `[patch.crates-io] vimp-engine-core = { path =
+// … }` — оно есть в игре, созданной с --core-path, версии в нём нет, и
+// проверка пина молча проходила бы
+const DEP_SECTIONS = new Set([
+  'dependencies',
+  'workspace.dependencies',
+  'build-dependencies',
+]);
+
+// объявление зависимости в обеих формах: inline (`dep = { … }` или
+// `dep = "x.y"`) и секцией (`[dependencies.dep]` … до следующей секции)
+function readDep(text, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const inline = new RegExp(`^\\s*${escaped}\\s*=\\s*(.+)$`, 'm');
+
+  for (const [header, body] of sections(text)) {
+    if (DEP_SECTIONS.has(header)) {
+      const found = body.match(inline)?.[1];
+
+      if (found) {
+        return found;
+      }
+    }
+
+    if ([...DEP_SECTIONS].some(dep => header === `${dep}.${name}`)) {
+      return body;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Секции TOML: заголовок без скобок и тело до следующего заголовка.
+ * @param {string} text
+ * @returns {Array<[string, string]>}
+ */
+function sections(text) {
+  const header = /^[ \t]*\[([^[\]\n]+)\][ \t]*$/gm;
+  const found = [];
+  let match = header.exec(text);
+
+  while (match !== null) {
+    const start = match.index + match[0].length;
+    const next = header.exec(text);
+
+    found.push([
+      match[1].trim(),
+      text.slice(start, next === null ? text.length : next.index),
+    ]);
+    match = next;
+  }
+
+  return found;
+}
+
+function readSection(text, name) {
+  return sections(text).find(([header]) => header === name)?.[1] ?? null;
+}

package/src/devtools/contract/rules/a6-manifest.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { ERROR, skip, verdict } from '../result.js';
+
+// dist/manifest.json — единственное, что мастер читает о собранной игре.
+// Расхождение id или битая ссылка в entries не ломает сборку: игра просто
+// не появляется в лобби (мастер пропускает её с console.warn).
+// entries.wasmNode обязан указывать внутрь dist/ — публикуется только он.
+export default {
+  id: 'A6',
+  name: 'manifestShape',
+  level: ERROR,
+  title: 'dist/manifest.json: id, entries on disk, roomDefaults coverage',
+
+  check(ctx) {
+    if (!ctx.manifest) {
+      return skip('not built — no dist/manifest.json');
+    }
+
+    const { manifest } = ctx;
+    const violations = [];
+
+    for (const [half, plugin] of [
+      ['host', ctx.hostPlugin],
+      ['client', ctx.clientPlugin],
+    ]) {
+      if (plugin && plugin.id !== manifest.id) {
+        violations.push(
+          `manifest id "${manifest.id}" differs from the ${half} plugin id ` +
+            `"${plugin.id}"`,
+        );
+      }
+    }
+
+    for (const [name, entry] of Object.entries(manifest.entries ?? {})) {
+      const rel =
+        name === 'wasmNode' ? entry : stripBase(entry, manifest.assetsBase);
+      const inside = path
+        .normalize(rel)
+        .replace(/^\.\//, '')
+        .replaceAll(path.sep, '/');
+
+      if (inside.startsWith('../')) {
+        violations.push(
+          `entries.${name} points outside dist/ ("${entry}") — only dist/ ` +
+            'is published',
+        );
+        continue;
+      }
+
+      if (!ctx.distFiles?.has(inside)) {
+        violations.push(`entries.${name} ("${entry}") is not in dist/`);
+      }
+    }
+
+    const roomForm = manifest.roomForm ?? [];
+    const defaults = manifest.roomDefaults ?? {};
+
+    for (const field of roomForm) {
+      // источник значения у поля бывает и вне roomDefaults: select по картам
+      // засеивается списком карт манифеста
+      if (defaults[field.name] === undefined && field.source !== 'maps') {
+        violations.push(
+          `roomForm field "${field.name}" has no roomDefaults value`,
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};
+
+function stripBase(entry, assetsBase) {
+  if (assetsBase && entry.startsWith(assetsBase)) {
+    return entry.slice(assetsBase.length);
+  }
+
+  return entry.replace(/^\/+/, '');
+}

package/src/devtools/contract/rules/b1-host-shape.js

@@ -0,0 +1,50 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// Поля HostPlugin, которые движок разыменовывает без проверок: отсутствие
+// любого даёт TypeError глубоко в onInit, за десяток кадров от причины.
+// chatCommands проверяется отдельно на «массив»: движок его итерирует.
+const REQUIRED = [
+  ['id', 'string'],
+  ['engineApi', 'number'],
+  ['createCore', 'function'],
+  ['gameConfig', 'object'],
+  ['authSchema', 'object'],
+  ['createModules', 'function'],
+  ['buildClientGameConfig', 'function'],
+];
+
+export default {
+  id: 'B1',
+  name: 'hostPluginShape',
+  level: ERROR,
+  title: 'HostPlugin exports every field the engine dereferences',
+
+  check(ctx) {
+    if (!ctx.hostPlugin) {
+      return skip('host plugin not loaded');
+    }
+
+    const violations = [];
+
+    for (const [field, type] of REQUIRED) {
+      const value = ctx.hostPlugin[field];
+
+      if (value === undefined || value === null) {
+        violations.push(`HostPlugin.${field} is missing`);
+      } else if (typeof value !== type) {
+        violations.push(
+          `HostPlugin.${field} is ${typeof value}, expected ${type}`,
+        );
+      }
+    }
+
+    if (!Array.isArray(ctx.hostPlugin.chatCommands)) {
+      violations.push(
+        'HostPlugin.chatCommands must be an array (use [] for none) — the ' +
+          'engine iterates it unguarded',
+      );
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/b10-respawns.js

@@ -0,0 +1,52 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// respawns[team].length — жёсткая вместимость команды на карте
+// (RoundManager отказывает в переходе, когда точек не хватает). Комната,
+// заявившая maxPlayers больше суммы точек, впускает лишних участников
+// наблюдателями и молча меньше, чем обещала.
+export default {
+  id: 'B10',
+  name: 'respawns',
+  level: ERROR,
+  title: 'every playing team has respawns and they cover maxPlayers',
+
+  check(ctx) {
+    const maps = ctx.gameConfig?.maps;
+    const teams = ctx.gameConfig?.teams;
+
+    if (!maps || !teams) {
+      return skip('no gameConfig.maps or gameConfig.teams');
+    }
+
+    const playing = Object.keys(teams).filter(
+      team => team !== ctx.gameConfig.spectatorTeam,
+    );
+    const maxPlayers = ctx.gameConfig.roomDefaults?.maxPlayers;
+    const violations = [];
+
+    for (const [name, map] of Object.entries(maps)) {
+      const respawns = map?.respawns ?? {};
+      let capacity = 0;
+
+      for (const team of playing) {
+        const points = respawns[team];
+
+        if (!Array.isArray(points) || !points.length) {
+          violations.push(`map "${name}": team "${team}" has no respawns`);
+          continue;
+        }
+
+        capacity += points.length;
+      }
+
+      if (maxPlayers !== undefined && capacity < maxPlayers) {
+        violations.push(
+          `map "${name}": ${capacity} respawn point(s) for ${maxPlayers} ` +
+            'players — the room is silently capped below roomDefaults.maxPlayers',
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/b2-engine-api.js

@@ -0,0 +1,47 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// engineApi живёт в трёх местах (манифест, HostPlugin, ClientPlugin) и во
+// всех трёх обязан быть импортом ENGINE_API_VERSION, а не числом: литерал
+// не расходится со сборкой движка в момент написания и молча расходится
+// через релиз, после чего плагин отклоняется гейтом совместимости.
+export default {
+  id: 'B2',
+  name: 'engineApiVersion',
+  level: ERROR,
+  title: 'engineApi matches ENGINE_API_VERSION in all three places',
+
+  check(ctx) {
+    const declared = [
+      ['host plugin', ctx.hostPlugin?.engineApi],
+      ['client plugin', ctx.clientPlugin?.engineApi],
+      ['manifest', ctx.manifest?.engineApi],
+    ].filter(([, value]) => value !== undefined);
+
+    if (!declared.length) {
+      return skip('neither plugin half nor manifest is available');
+    }
+
+    const violations = [];
+
+    for (const [where, value] of declared) {
+      if (value !== ctx.engineApi) {
+        violations.push(
+          `${where} declares engineApi v${value}, this engine is v${ctx.engineApi}`,
+        );
+      }
+    }
+
+    for (const [where, text] of [
+      ['src/host/index.js', ctx.hostText],
+      ['src/client/index.js', ctx.clientText],
+    ]) {
+      if (text && !text.includes('ENGINE_API_VERSION')) {
+        violations.push(
+          `${where} hardcodes engineApi — import ENGINE_API_VERSION instead`,
+        );
+      }
+    }
+
+    return verdict(violations);
+  },
+};

package/src/devtools/contract/rules/b3-game-config-shape.js

@@ -0,0 +1,27 @@
+import { assertGameConfigShape } from '../../../lib/gamePlugin.js';
+import { ERROR, skip, verdict } from '../result.js';
+
+// Тот же гейт, что стоит на боевом пути загрузки плагина
+// (lib/gamePlugin.js): девять обязательных путей gameConfig плюс связь
+// spectatorTeam ↔ teams. Дублировать его список здесь нельзя — он обязан
+// эволюционировать в одном месте.
+export default {
+  id: 'B3',
+  name: 'gameConfigShape',
+  level: ERROR,
+  title: 'gameConfig has the nine paths the engine reads before any logic',
+
+  check(ctx) {
+    if (!ctx.hostPlugin) {
+      return skip('host plugin not loaded');
+    }
+
+    try {
+      assertGameConfigShape(ctx.hostPlugin);
+    } catch (error) {
+      return verdict([error.message]);
+    }
+
+    return verdict([]);
+  },
+};

package/src/devtools/contract/rules/b4-teams.js

@@ -0,0 +1,37 @@
+import { ERROR, skip, verdict } from '../result.js';
+
+// teams/spectatorTeam. Опечатка в spectatorTeam ловится гейтом B3; здесь —
+// вторая половина контракта: играющая команда должна быть хотя бы одна,
+// иначе раунд некому начинать, а все участники висят наблюдателями.
+export default {
+  id: 'B4',
+  name: 'teams',
+  level: ERROR,
+  title: 'spectatorTeam is a teams key and at least one playing team exists',
+
+  check(ctx) {
+    const teams = ctx.gameConfig?.teams;
+
+    if (!teams) {
+      return skip('no gameConfig.teams');
+    }
+
+    const { spectatorTeam } = ctx.gameConfig;
+    const violations = [];
+
+    if (teams[spectatorTeam] === undefined) {
+      violations.push(
+        `spectatorTeam "${spectatorTeam}" is not a key of teams ` +
+          `(${Object.keys(teams).join(', ')})`,
+      );
+    }
+
+    const playing = Object.keys(teams).filter(team => team !== spectatorTeam);
+
+    if (!playing.length) {
+      violations.push('teams declares no playing team besides the spectators');
+    }
+
+    return verdict(violations);
+  },
+};