vimp-engine 0.22.0 → 0.23.0

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

@@ -1,11 +1,31 @@
-import { assertGameConfigShape } from '../../../lib/gamePlugin.js';
-import { ERROR, skip, verdict } from '../result.js';
+import {
+  REQUIRED_GAME_CONFIG_PATHS,
+  createGameConfigView,
+} from '../../../lib/gameConfigView.js';
+import { ERROR, WARN, skip, verdict } from '../result.js';
 
 // Тот же гейт, что стоит на боевом пути загрузки плагина
-// (lib/gamePlugin.js): обязательные пути gameConfig плюс связь
+// (lib/gameConfigView.js): обязательные пути gameConfig плюс связь
 // spectatorTeam ↔ teams (под noSpectators — «ровно одна команда»).
 // Дублировать его список здесь нельзя — он обязан эволюционировать в одном
 // месте.
+//
+// Всё, что не в REQUIRED, движок подставляет сам (И2 этапа 2 плана
+// plugin-forward-compat) — это не отказ. Но полагаться на движковое
+// умолчание разработчик должен осознанно, поэтому необъявленные поля
+// перечисляются предупреждением.
+const DEFAULTED = [
+  'roomDefaults.maxPlayers',
+  'parts.weapons',
+  'parts.friendlyFire',
+  'panel.fields',
+  'spectatorTeam',
+];
+
+function getPath(source, dottedPath) {
+  return dottedPath.split('.').reduce((value, key) => value?.[key], source);
+}
+
 export default {
   id: 'B3',
   name: 'gameConfigShape',
@@ -18,11 +38,32 @@ export default {
     }
 
     try {
-      assertGameConfigShape(ctx.hostPlugin);
+      createGameConfigView(ctx.hostPlugin.gameConfig, ctx.hostPlugin.id);
     } catch (error) {
       return verdict([error.message]);
     }
 
-    return verdict([]);
+    // noSpectators — своя ветка контракта: spectatorTeam там не бывает
+    const declared = ctx.hostPlugin.gameConfig;
+    const paths =
+      declared?.noSpectators === true
+        ? DEFAULTED.filter(path => path !== 'spectatorTeam')
+        : DEFAULTED;
+
+    const relied = paths.filter(path => {
+      const value = getPath(declared, path);
+
+      return value === undefined || value === null;
+    });
+
+    return verdict(
+      relied.map(
+        path =>
+          `gameConfig.${path} is not declared — the engine falls back to ` +
+          'its own default; declare it if the game means something else',
+      ),
+      `required: ${REQUIRED_GAME_CONFIG_PATHS.join(', ')}`,
+      WARN,
+    );
   },
 };

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

@@ -17,7 +17,10 @@ export default {
       return skip('no gameConfig.teams');
     }
 
-    const { spectatorTeam } = ctx.gameConfig;
+    // эффективное значение, а не объявленное: движок выводит spectatorTeam
+    // из команды `spectators`, и игра вправе его не писать (И2)
+    const spectatorTeam = ctx.gameConfigView?.spectatorTeam ?? null;
+    const declared = ctx.gameConfig.spectatorTeam;
     const violations = [];
 
     if (ctx.gameConfig.noSpectators === true) {
@@ -33,9 +36,9 @@ export default {
       return verdict(violations);
     }
 
-    if (teams[spectatorTeam] === undefined) {
+    if (declared !== undefined && teams[declared] === undefined) {
       violations.push(
-        `spectatorTeam "${spectatorTeam}" is not a key of teams ` +
+        `spectatorTeam "${declared}" is not a key of teams ` +
           `(${Object.keys(teams).join(', ')})`,
       );
     }

package/src/devtools/contract/rules/b5-room-form.js

@@ -1,13 +1,26 @@
-import { ERROR, skip, verdict } from '../result.js';
+import { ERROR, WARN, skip, verdict } from '../result.js';
 import { anchorPattern } from '../../../lib/formPattern.js';
+import {
+  formControls,
+  ACTIVE_FORM_CONTROLS,
+} from '../../../lib/formControls.js';
 
 // roomForm. Поле вне белого списка форма показывает, лобби отправляет, а
 // хост молча выбрасывает — правило игры, построенное на своей настройке
-// комнаты, не работает и ничего об этом не сообщает. Контролов в v3 ровно
-// четыре: неизвестный пропускается с console.error. `regExp` едет в манифесте
-// строкой и компилируется уже у игрока — некомпилируемая ловится здесь.
-const HONOURED = ['maps', 'maxPlayers', 'map', 'roundTime', 'mapTime', 'friendlyFire'];
-const CONTROLS = ['text', 'select', 'checkbox', 'radio'];
+// комнаты, не работает и ничего об этом не сообщает. Контрол проверяется по
+// реестру (lib/formControls.js): неизвестный пропускается с console.error,
+// выведенный из эксплуатации строится алиасом и потому только WARN — новая
+// игра его писать не должна, старая продолжает работать. `regExp` едет в
+// манифесте строкой и компилируется уже у игрока — некомпилируемая ловится
+// здесь.
+const HONOURED = [
+  'maps',
+  'maxPlayers',
+  'map',
+  'roundTime',
+  'mapTime',
+  'friendlyFire',
+];
 
 export default {
   id: 'B5',
@@ -23,6 +36,7 @@ export default {
     }
 
     const violations = [];
+    const retired = [];
 
     for (const field of roomForm) {
       if (!HONOURED.includes(field.name)) {
@@ -32,10 +46,20 @@ export default {
         );
       }
 
-      if (!CONTROLS.includes(field.control)) {
+      if (!formControls.has(field.control)) {
         violations.push(
           `roomForm field "${field.name}": control "${field.control}" does ` +
-            `not exist (${CONTROLS.join(', ')})`,
+            `not exist (${ACTIVE_FORM_CONTROLS.join(', ')})`,
+        );
+      } else if (formControls.isRetired(field.control)) {
+        const entry = formControls.get(field.control);
+
+        retired.push(
+          `roomForm field "${field.name}": control "${field.control}" was ` +
+            `retired in plugin API v${entry.retiredIn} — it still works ` +
+            `(the engine builds it as "${formControls.resolve(field.control)}" ` +
+            `forever), but a new game should declare ` +
+            `"${formControls.resolve(field.control)}" itself`,
         );
       }
 
@@ -54,6 +78,14 @@ export default {
       }
     }
 
+    if (violations.length === 0 && retired.length > 0) {
+      return verdict(
+        retired,
+        'retired controls still build, via aliases',
+        WARN,
+      );
+    }
+
     return verdict(violations);
   },
 };

package/src/devtools/contract/rules/c4-component-dependencies.js

@@ -1,20 +1,15 @@
 import { ERROR, WARN, skip, verdict } from '../result.js';
+import { SERVICES } from '../../../config/clientServices.js';
 
-// Движковых сервисов ровно пять (client/main.js), но пул ими не
-// исчерпывается: игра доливает туда свои через ClientPlugin.hooks.services(core)
-// — например геометрию предсказанной динамики карты
-// (docs/en/plugin-api.md «hooks.services»). Незнакомое имя не ошибка для
-// движка: part получает undefined и рисует пустоту — карта без assetsBase
-// выглядит как чистый холст без единой строки в консоли, ради этого правило
-// и существует.
-const SERVICES = [
-  'renderer',
-  'soundManager',
-  'assetsBase',
-  'localPlayer',
-  // места в глобальном топе (snakes-v3 этап 4)
-  'accolades',
-];
+// Движковый пул сервисов держит реестр (config/clientServices.js), но пул
+// ими не исчерпывается: игра доливает туда свои через
+// ClientPlugin.hooks.services(core) — например геометрию предсказанной
+// динамики карты (docs/en/plugin-api.md «hooks.services»). Незнакомое имя не
+// ошибка для движка: part получает undefined и рисует пустоту — карта без
+// assetsBase выглядит как чистый холст без единой строки в консоли, ради
+// этого правило и существует. Правило остаётся ERROR: оно работает на этапе
+// разработки игры, а не в рантайме.
+export { SERVICES };
 
 export default {
   id: 'C4',

package/src/devtools/surface/abiParse.js

@@ -0,0 +1,175 @@
+// Разбор `core/src/abi.rs` — единственный раздел слепка плагинной
+// поверхности, который нельзя собрать импортом: методы wasm-ABI живут внутри
+// `macro_rules!`, раскрывающихся уже в крейте игры. Слепок читает файл как
+// текст и вытаскивает имена и нормализованные сигнатуры `pub fn`.
+//
+// Разбор обязан ПАДАТЬ, а не возвращать пустоту: молчаливо пустой раздел
+// слепка пропустит любое нарушение И1/И3 (plan/plugin-forward-compat).
+
+// имя макроса → раздел слепка (`abi.game` / `abi.client`)
+const MACRO_SECTIONS = {
+  // имена макросов Rust — строками: camelCase к ним неприменим
+  'export_game_core_abi': 'game',
+  'export_client_core_abi': 'client',
+};
+
+/**
+ * @param {string} source - Содержимое `core/src/abi.rs`.
+ * @returns {{game: Object[], client: Object[]}} Методы ABI по разделам,
+ *   каждый — { name, args, ret }, отсортированные по имени.
+ */
+export function parseAbi(source) {
+  const blocks = splitMacros(source);
+
+  if (blocks.length === 0) {
+    throw new Error(
+      'abiParse: no macro_rules! block found in core/src/abi.rs — the file ' +
+        'was restructured; fix the parser instead of letting the surface ' +
+        'snapshot go silently empty',
+    );
+  }
+
+  const sections = {};
+
+  for (const block of blocks) {
+    const section = MACRO_SECTIONS[block.macro];
+
+    if (!section) {
+      continue; // макрос вне ABI плагина — не часть поверхности
+    }
+
+    const methods = parseMethods(block.body);
+
+    if (methods.length === 0) {
+      throw new Error(
+        `abiParse: macro_rules! ${block.macro} yielded no "pub fn" — the ` +
+          'file was restructured; fix the parser',
+      );
+    }
+
+    sections[section] = methods.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  for (const [macro, section] of Object.entries(MACRO_SECTIONS)) {
+    if (!sections[section]) {
+      throw new Error(
+        `abiParse: macro_rules! ${macro} not found in core/src/abi.rs`,
+      );
+    }
+  }
+
+  return sections;
+}
+
+// тело каждого `macro_rules! <name> { … }` — от имени до парной скобке
+function splitMacros(source) {
+  const re = /macro_rules!\s+([a-z_0-9]+)\s*\{/g;
+  const blocks = [];
+  let match;
+
+  while ((match = re.exec(source)) !== null) {
+    const open = re.lastIndex - 1;
+    const close = matchBrace(source, open, '{', '}');
+
+    blocks.push({
+      macro: match[1],
+      body: source.slice(open + 1, close),
+    });
+  }
+
+  return blocks;
+}
+
+// `pub fn name(args) -> ret` внутри тела макроса; тело метода пропускается
+function parseMethods(body) {
+  const re = /pub\s+fn\s+([a-z_0-9]+)\s*\(/g;
+  const methods = [];
+  let match;
+
+  while ((match = re.exec(body)) !== null) {
+    const open = re.lastIndex - 1;
+    const close = matchBrace(body, open, '(', ')');
+    const tail = body.slice(close + 1);
+    const arrow = /^\s*->([^{;]+)/.exec(tail);
+
+    methods.push({
+      name: match[1],
+      args: splitArgs(body.slice(open + 1, close)).map(normalizeType),
+      ret: arrow ? normalizeType(arrow[1]) : '()',
+    });
+  }
+
+  return methods;
+}
+
+// индекс скобки, парной открывающей на позиции `open`
+function matchBrace(source, open, openChar, closeChar) {
+  let depth = 0;
+
+  for (let i = open; i < source.length; i += 1) {
+    if (source[i] === openChar) {
+      depth += 1;
+    } else if (source[i] === closeChar) {
+      depth -= 1;
+
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+
+  throw new Error(`abiParse: unbalanced ${openChar} at offset ${open}`);
+}
+
+// список аргументов по запятым верхнего уровня; получатель (`&self`,
+// `&mut self`) в сигнатуру не входит — он не часть бинарного контракта
+function splitArgs(list) {
+  const args = [];
+  let depth = 0;
+  let current = '';
+
+  for (const ch of list) {
+    if (ch === '<' || ch === '(' || ch === '[') {
+      depth += 1;
+    } else if (ch === '>' || ch === ')' || ch === ']') {
+      depth -= 1;
+    }
+
+    if (ch === ',' && depth === 0) {
+      args.push(current);
+      current = '';
+      continue;
+    }
+
+    current += ch;
+  }
+
+  args.push(current);
+
+  return args
+    .map(arg => arg.trim())
+    .filter(arg => arg.length > 0 && !/^&?\s*(mut\s+)?self$/.test(arg))
+    .map(arg => {
+      const colon = arg.indexOf(':');
+
+      // аргумент без имени в этих макросах не встречается: имя есть всегда
+      return colon === -1 ? arg : arg.slice(colon + 1);
+    });
+}
+
+// Стабильная строка типа: меняется тогда и только тогда, когда меняется
+// бинарный контракт. Ссылка/`mut`/пробелы/путь до wasm-bindgen на него не
+// влияют; `Result<T, JsError>` сворачивается в `Result<T>` — вариант ошибки
+// у всех методов один.
+function normalizeType(type) {
+  const flat = type
+    .replaceAll('::wasm_bindgen::', '')
+    .replaceAll('wasm_bindgen::', '')
+    .replace(/\bmut\b/g, '')
+    .replaceAll('&', '')
+    .replace(/\s+/g, '');
+
+  return flat.replace(/^Result<(.*),JsError>$/, 'Result<$1>');
+}
+
+export default parseAbi;