@besales/mcp 0.48.0 → 1.0.0-beta.2

package/scripts/registry-diff.mjs

@@ -0,0 +1,502 @@
+// Сравнение отгруженного реестра инструментов с реестром ветки v2.
+//
+// Меряются ТРИ разных отказа, и путать их нельзя:
+//   состав    — инструмента в v2 нет вовсе (после переезда он исчезает у оператора);
+//   контракт  — поле или значение, которое отгруженный инструмент принимает, а v2-двойник не знает
+//               (после переезда функция недостижима; а если адрес совпал — отгруженный клиент уже
+//               сегодня получает 400, потому что приёмная сторона отвергает незнакомое поле целиком);
+//   схема↔zod — поле объявлено в JSON-реестре, но фактический фильтр аргументов (zod) его не знает,
+//               то есть инструмент молча срезает значение вместо отказа.
+//
+// Обе сравниваемые стороны первых двух проверок — реестры одного вида (рукописный JSON), поэтому
+// сравнение по ограничениям здесь не даёт шума: замер на 154 общих инструментах дал 18 расхождений
+// на все измерения вместе.
+
+const MAX_DEPTH = 8;
+const MAX_REF_HOPS = 8;
+
+function siblingsOf(node) {
+  const { $ref: _ignored, ...siblings } = node;
+  return siblings;
+}
+
+/**
+ * Разрешает локальную ссылку `$ref` в тело определения из `$defs`.
+ *
+ * ⛔ Fail-closed. Неразрешимая ссылка РОНЯЕТ сверку, а не «остаётся как есть»: узел с одним лишь
+ * `$ref` не имеет ни `enum`, ни `type`, ни `properties` — то есть для обхода он неотличим от
+ * схемы БЕЗ ограничений. Именно так и выглядела слепота, ради которой пишется эта функция: пока
+ * ссылки не разворачивались, любое расхождение внутри общего определения проходило зелёным.
+ * Оставить битую ссылку молча значило бы сохранить ту же дыру под другим именем.
+ *
+ * Соседние ключи узла-ссылки побеждают тело определения: `{"$ref": …, "description": …}` не
+ * должен терять собственное описание.
+ */
+export function resolveSchemaRef(node, root, context) {
+  let current = node;
+  for (let hop = 0; hop <= MAX_REF_HOPS; hop += 1) {
+    if (current === null || typeof current !== 'object' || typeof current.$ref !== 'string') {
+      return current;
+    }
+    const pointer = current.$ref;
+    if (pointer === '#') {
+      // Указатель на корень схемы — законный локальный случай, а не внешний документ. Проверка
+      // объектности та же, что у прочих целей: нечестный корень дал бы пустой узел, то есть
+      // «ограничений нет».
+      if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+        throw new Error(`${context}: указатель # ведёт не на объект-схему`);
+      }
+      current = { ...root, ...siblingsOf(current) };
+      continue;
+    }
+    if (!pointer.startsWith('#/')) {
+      throw new Error(
+        `${context}: внешняя ссылка ${pointer} — её документ сверке недоступен, ограничения внутри неё проверить нечем`,
+      );
+    }
+    let target = root;
+    for (const rawSegment of pointer.slice(2).split('/')) {
+      const segment = rawSegment.replace(/~1/gu, '/').replace(/~0/gu, '~');
+      target = target === null || typeof target !== 'object' ? undefined : target[segment];
+    }
+    if (target === undefined) {
+      throw new Error(`${context}: указатель ${pointer} никуда не ведёт`);
+    }
+    // ⛔ Цель обязана быть ОБЪЕКТОМ-схемой. `false` в JSON Schema означает «не принимать ничего»,
+    // `true` — «принимать всё», массив и скаляр схемой не являются вовсе; спред любого из них дал
+    // бы пустой узел, то есть «ограничений нет» — тот самый fail-open, ради устранения которого
+    // разыменование и написано.
+    if (target === null || typeof target !== 'object' || Array.isArray(target)) {
+      throw new Error(
+        `${context}: указатель ${pointer} ведёт не на объект-схему (${JSON.stringify(target)})`,
+      );
+    }
+    current = { ...target, ...siblingsOf(current) };
+  }
+  throw new Error(`${context}: цепочка ссылок длиннее ${MAX_REF_HOPS} переходов — вероятен цикл`);
+}
+
+/**
+ * Ограничения одного узла схемы, которые имеет смысл сравнивать между двумя реестрами.
+ *
+ * `const` и одноэлементный `enum` — одно и то же множество допустимых значений, записанное разными
+ * генераторами схем. Не сведи их к общему виду — и подтверждение платного запуска (`literal(true)`
+ * против `enum:[true]`) числилось бы расхождением, которого нет.
+ */
+function constraintsOf(node, required) {
+  const values = Array.isArray(node.enum)
+    ? node.enum
+    : node.const !== undefined
+      ? [node.const]
+      : undefined;
+  return {
+    type: node.type,
+    enum: values === undefined ? undefined : [...values].map(String).sort().join('|'),
+    minimum: node.minimum,
+    maximum: node.maximum,
+    minLength: node.minLength,
+    maxLength: node.maxLength,
+    minItems: node.minItems,
+    maxItems: node.maxItems,
+    pattern: node.pattern,
+    format: node.format,
+    required,
+  };
+}
+
+/** Ограничения веток `anyOf`/`oneOf` свойства — невидимым ключом: в сравнение и сериализацию сам узел не меняет. */
+const ALTERNATIVES = Symbol('alternatives');
+
+/**
+ * Ограничения узла вместе с его ветками `anyOf`/`oneOf`.
+ *
+ * ⛔ У свойства-объединения («дата ИЛИ момент») собственных `format`/`type` бывает не видно: без веток сверка читала
+ * бы его как «формат не объявлен» и заводила строку отставания там, где отгруженная форма по-прежнему принимается.
+ * Ветка наследует ограничения узла, которых сама не задаёт.
+ */
+function constraintsWithAlternatives(node, required, root, context) {
+  const own = constraintsOf(node, required);
+  const branches = [
+    ...(Array.isArray(node.anyOf) ? node.anyOf : []),
+    ...(Array.isArray(node.oneOf) ? node.oneOf : []),
+  ];
+  if (branches.length === 0) return own;
+  own[ALTERNATIVES] = branches.map((branch) => {
+    const constraints = constraintsOf(resolveSchemaRef(branch, root, context), required);
+    return Object.fromEntries(
+      Object.entries(own).map(([key, value]) => [
+        key,
+        constraints[key] === undefined ? value : constraints[key],
+      ]),
+    );
+  });
+  return own;
+}
+
+/**
+ * Пути свойств JSON-схемы с их ограничениями: `a`, `a.b`, `a[].c`.
+ * Ветки `oneOf`/`anyOf`/`allOf` разворачиваются в объединение — инструмент принимает любую из них.
+ */
+export function schemaConstraints(
+  node,
+  prefix = '',
+  out = new Map(),
+  depth = 0,
+  root = node,
+  context = 'схема',
+) {
+  if (node === null || typeof node !== 'object' || depth > MAX_DEPTH) return out;
+  node = resolveSchemaRef(node, root, context);
+  if (node === null || typeof node !== 'object') return out;
+  for (const key of ['oneOf', 'anyOf', 'allOf']) {
+    if (Array.isArray(node[key])) {
+      for (const branch of node[key])
+        schemaConstraints(branch, prefix, out, depth + 1, root, context);
+    }
+  }
+  if (node.properties !== undefined && node.properties !== null) {
+    const required = new Set(Array.isArray(node.required) ? node.required : []);
+    for (const [name, child] of Object.entries(node.properties)) {
+      const path = prefix === '' ? name : `${prefix}.${name}`;
+      if (!out.has(path)) {
+        out.set(
+          path,
+          constraintsWithAlternatives(
+            resolveSchemaRef(child, root, context),
+            required.has(name),
+            root,
+            context,
+          ),
+        );
+      }
+      schemaConstraints(child, path, out, depth + 1, root, context);
+    }
+  }
+  if (node.items !== undefined && node.items !== null) {
+    // Ограничения САМОГО элемента массива (тип, перечисление, формат) обязаны попасть в сравнение:
+    // сужение `items.enum` при одинаковом объявлении родителя не меняет ни одного пути свойств, но
+    // отвергает вызов отгруженного клиента.
+    if (!out.has(`${prefix}[]`)) {
+      out.set(
+        `${prefix}[]`,
+        constraintsWithAlternatives(
+          resolveSchemaRef(node.items, root, context),
+          false,
+          root,
+          context,
+        ),
+      );
+    }
+    schemaConstraints(node.items, `${prefix}[]`, out, depth + 1, root, context);
+  }
+  return out;
+}
+
+/**
+ * Сохраняется ли путь в ВЫХОДНОЙ схеме фильтра. Входная схема Zod разрешает лишние поля даже
+ * у объекта, который срезает их при разборе; выходная различает strip и passthrough.
+ * Именованный дочерний объект проверяется сам: passthrough родителя не защищает его поля.
+ */
+export function schemaRetainsPath(node, path, root = node, depth = 0) {
+  // Полностью пройденный путь не требует ещё одного спуска (nullable добавляет ветку схемы).
+  if (depth > MAX_DEPTH && path !== '')
+    throw new Error(`Путь фильтра глубже ${MAX_DEPTH} уровней: ${path}`);
+  if (node === true) return true;
+  if (node === false || node === null || typeof node !== 'object') return false;
+  node = resolveSchemaRef(node, root, 'выходная схема фильтра');
+  if (path === '') return true;
+
+  for (const key of ['anyOf', 'oneOf', 'allOf']) {
+    if (Array.isArray(node[key])) {
+      const retained = node[key].map((branch) => schemaRetainsPath(branch, path, root, depth + 1));
+      // Пересечение Zod сливает результаты разбора: поле достаточно сохранить в одной части.
+      if (retained.some(Boolean)) return true;
+    }
+  }
+
+  const hasShape =
+    node.type !== undefined ||
+    node.properties !== undefined ||
+    node.items !== undefined ||
+    node.additionalProperties !== undefined;
+  // Неограниченное значение (z.unknown / passthrough) сохраняет и всё вложенное содержимое.
+  if (!hasShape && node.anyOf === undefined && node.oneOf === undefined && node.allOf === undefined)
+    return true;
+  if (path.startsWith('[]')) {
+    return schemaRetainsPath(node.items, path.slice(2).replace(/^\./, ''), root, depth + 1);
+  }
+  const [name] = path.split(/[.\[]/, 1);
+  const rest = path.slice(name.length).replace(/^\./, '');
+  if (Object.hasOwn(node.properties ?? {}, name)) {
+    return schemaRetainsPath(node.properties[name], rest, root, depth + 1);
+  }
+  if (node.additionalProperties === true) return true;
+  return schemaRetainsPath(node.additionalProperties, rest, root, depth + 1);
+}
+
+/** Независимый обход перечней: ветки объединений не теряются при записи ограничений первого пути. */
+export function enumValuesByPath(schema) {
+  const found = new Map();
+  const stack = new Set();
+  function visit(raw, path) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return;
+    if (stack.has(raw)) throw new Error(`перечни::${path}: цикл схемы`);
+    stack.add(raw);
+    try {
+      const node = resolveSchemaRef(raw, schema, `перечни::${path}`);
+      if (node.type === 'null') return;
+      const values = [
+        ...(Array.isArray(node.enum) ? node.enum : []),
+        ...(Object.hasOwn(node, 'const') ? [node.const] : []),
+      ].filter((value) => value !== null);
+      if (values.length > 0) {
+        const merged = found.get(path) ?? new Map();
+        for (const value of values) merged.set(JSON.stringify(value), value);
+        found.set(path, merged);
+      }
+      for (const kind of ['anyOf', 'oneOf', 'allOf']) {
+        for (const branch of node[kind] ?? []) visit(branch, path);
+      }
+      for (const [name, child] of Object.entries(node.properties ?? {}))
+        visit(child, path === '' ? name : `${path}.${name}`);
+      if (node.items !== undefined) visit(node.items, `${path}[]`);
+      for (const item of node.prefixItems ?? []) visit(item, `${path}[]`);
+    } finally {
+      stack.delete(raw);
+    }
+  }
+  visit(schema, '');
+  return new Map(
+    [...found].map(([path, values]) => [
+      path,
+      [...values.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, value]) => value),
+    ]),
+  );
+}
+
+function differingKeys(shipped, local) {
+  return Object.keys(shipped).filter(
+    (key) => JSON.stringify(shipped[key]) !== JSON.stringify(local[key]),
+  );
+}
+
+/**
+ * @returns {{
+ *   missingTools: string[],
+ *   contractLag: Array<{ tool: string, path: string, kind: 'MISSING_FIELD' | 'CONSTRAINT', shipped: unknown, v2: unknown }>,
+ *   v2Only: string[],
+ * }}
+ */
+export function diffRegistries(shippedTools, localTools, toolSuccessors = {}) {
+  const local = new Map(localTools.map((tool) => [tool.name, tool]));
+  const shippedNames = new Set(shippedTools.map((tool) => tool.name));
+  const successorTargets = new Set();
+  for (const [shippedName, v2Name] of Object.entries(toolSuccessors)) {
+    if (!shippedNames.has(shippedName)) {
+      throw new Error(
+        `Преемник объявлен для отсутствующего отгруженного инструмента: ${shippedName}`,
+      );
+    }
+    if (typeof v2Name !== 'string' || v2Name.length === 0 || v2Name === shippedName) {
+      throw new Error(`Некорректный преемник ${shippedName}: ${String(v2Name)}`);
+    }
+    if (local.has(shippedName)) {
+      throw new Error(`Преемник ${shippedName} протух: старое имя уже существует в v2`);
+    }
+    if (!local.has(v2Name)) {
+      throw new Error(
+        `Преемник ${shippedName} указывает на отсутствующий v2-инструмент: ${v2Name}`,
+      );
+    }
+    if (shippedNames.has(v2Name) || successorTargets.has(v2Name)) {
+      throw new Error(`v2-инструмент ${v2Name} неоднозначно сопоставлен отгруженной поверхности`);
+    }
+    successorTargets.add(v2Name);
+  }
+  const missingTools = [];
+  const contractLag = [];
+
+  for (const shipped of shippedTools) {
+    const successorName = toolSuccessors[shipped.name];
+    const mine = local.get(successorName ?? shipped.name);
+    if (mine === undefined) {
+      missingTools.push(shipped.name);
+      continue;
+    }
+    // ⛔ Переименование обязано быть видно ДВУМЯ фактами, а не одним. Преемник объясняет, ЧЕМ
+    // заменён инструмент, и позволяет сверить схемы пофайлово — но отгруженное ИМЯ при этом
+    // исчезает с поверхности, и клиент, зовущий его сегодня, получит «инструмент не найден».
+    // Пряча имя из `missingTools`, сторож переставал показывать именно этот, клиентский, разрыв.
+    // Тот же приём уже применён к переименованию инструментов ревизора диалогов.
+    if (successorName !== undefined) {
+      missingTools.push(shipped.name);
+    }
+    const shippedSchema = shipped.inputSchema ?? {};
+    const localSchema = mine.inputSchema ?? {};
+    const shippedPaths = schemaConstraints(
+      shippedSchema,
+      '',
+      new Map(),
+      0,
+      shippedSchema,
+      `отгруженный ${shipped.name}`,
+    );
+    const localPaths = schemaConstraints(
+      localSchema,
+      '',
+      new Map(),
+      0,
+      localSchema,
+      `v2 ${mine.name}`,
+    );
+    // Walking only shipped paths misses a new mandatory root argument entirely.
+    // Optional extensions remain harmless; a required addition breaks the old call.
+    const localRoot = resolveSchemaRef(localSchema, localSchema, `v2 ${mine.name}`);
+    for (const path of localRoot.required ?? []) {
+      if (!shippedPaths.has(path) && localPaths.has(path)) {
+        contractLag.push({
+          tool: shipped.name,
+          path: `${path}#required`,
+          kind: 'CONSTRAINT',
+          shipped: false,
+          v2: true,
+        });
+      }
+    }
+    for (const [path, constraints] of shippedPaths) {
+      const mineConstraints = localPaths.get(path);
+      if (mineConstraints === undefined) {
+        contractLag.push({
+          tool: shipped.name,
+          path,
+          kind: 'MISSING_FIELD',
+          shipped: constraints.type ?? 'any',
+          v2: null,
+        });
+        continue;
+      }
+      // Отгруженная форма, которую держит хотя бы одна ветка объединения v2, по-прежнему принимается.
+      const candidates = [mineConstraints, ...(mineConstraints[ALTERNATIVES] ?? [])];
+      if (candidates.some((candidate) => differingKeys(constraints, candidate).length === 0))
+        continue;
+      for (const key of differingKeys(constraints, mineConstraints)) {
+        contractLag.push({
+          tool: shipped.name,
+          path: `${path}#${key}`,
+          kind: 'CONSTRAINT',
+          shipped: constraints[key] ?? null,
+          v2: mineConstraints[key] ?? null,
+        });
+      }
+    }
+  }
+
+  return {
+    missingTools: missingTools.sort(),
+    contractLag: contractLag.sort((a, b) =>
+      a.tool === b.tool ? a.path.localeCompare(b.path) : a.tool.localeCompare(b.tool),
+    ),
+    v2Only: localTools
+      .map((tool) => tool.name)
+      .filter((name) => !shippedNames.has(name) && !successorTargets.has(name))
+      .sort(),
+  };
+}
+
+/**
+ * Ключ строки реестра отставания: расхождение адресуется парой, а не одним именем инструмента.
+ *
+ * В ключ входят и САМИ значения: иначе строка, объявленная для предела «4000 против 2000», молча
+ * накрыла бы будущее «6000 против 1000» — путь тот же, решение другое, а ратификации никакой.
+ */
+export function lagKey(entry) {
+  return `${entry.tool}::${entry.path}::${JSON.stringify(entry.shipped)}→${JSON.stringify(entry.v2)}`;
+}
+
+/**
+ * Сверка найденного отставания с объявленным реестром — в ОБЕ стороны.
+ * Незаявленное отставание означает новую дыру; заявленное, но исчезнувшее — протухшую строку,
+ * которая иначе стала бы способом молча пропустить будущее расхождение под тем же именем.
+ */
+export const LAG_SEVERITIES = [
+  'LIVE_400',
+  'SCHEMA_LOOSER',
+  'ROUTE_MOVED',
+  'ROUTE_ABSENT',
+  'TOOL_ABSENT',
+  'DELIBERATE',
+];
+const OWNER_PATTERN = /^TASK-\d+(?:\.\d+)+$/u;
+const DECISION_REF = /decision:\d+(?:\.\d+)+:[^\s;,]+/u;
+
+function hasReason(value) {
+  return (
+    typeof value === 'string' &&
+    value.replace(/decision:[^\s;,]+/gu, '').replace(/[;\s]/gu, '') !== ''
+  );
+}
+function hasDecision(row) {
+  return row?.owner !== 'DELIBERATE' || DECISION_REF.test(row.reason ?? '');
+}
+
+export function validLagOwner(owner) {
+  return typeof owner === 'string' && (owner === 'DELIBERATE' || OWNER_PATTERN.test(owner));
+}
+
+export const LAG_SECTIONS = [
+  'missingTools',
+  'contractLag',
+  'legacyActionLag',
+  'routeLag',
+  'responseLag',
+  'optionalInputExtensions',
+  'contractExtensions',
+];
+
+/** Осознанное расхождение не имеет задачи, которая когда-нибудь снимет его. */
+export function lagMetadataErrors(registry) {
+  return LAG_SECTIONS.flatMap((section) =>
+    Object.entries(registry[section] ?? {})
+      .filter(
+        ([, row]) =>
+          !hasReason(row?.reason) ||
+          !hasDecision(row) ||
+          !validLagOwner(row?.owner) ||
+          ![...LAG_SEVERITIES, 'LIVE_422', 'RESPONSE_ABSENT'].includes(row?.severity) ||
+          (row?.owner === 'DELIBERATE') !== (row?.severity === 'DELIBERATE'),
+      )
+      .map(([key]) => `${section}:${key}`),
+  ).sort();
+}
+
+/** Пустая отписка — не объявление: строка обязана называть причину, владельца и тяжесть из словаря. */
+function incompleteEntries(section) {
+  return Object.entries(section ?? {})
+    .filter(
+      ([, value]) =>
+        !hasReason(value?.reason) ||
+        !hasDecision(value) ||
+        !validLagOwner(value?.owner) ||
+        !LAG_SEVERITIES.includes(value?.severity) ||
+        (value?.owner === 'DELIBERATE') !== (value?.severity === 'DELIBERATE'),
+    )
+    .map(([key]) => key);
+}
+
+export function reconcileWithRegistry(diff, registry) {
+  const declaredMissing = new Set(Object.keys(registry.missingTools ?? {}));
+  const declaredLag = new Set(Object.keys(registry.contractLag ?? {}));
+  const foundMissing = new Set(diff.missingTools);
+  const foundLag = new Set(diff.contractLag.map(lagKey));
+
+  return {
+    undeclaredMissing: [...foundMissing].filter((name) => !declaredMissing.has(name)).sort(),
+    staleMissing: [...declaredMissing].filter((name) => !foundMissing.has(name)).sort(),
+    undeclaredLag: [...foundLag].filter((key) => !declaredLag.has(key)).sort(),
+    staleLag: [...declaredLag].filter((key) => !foundLag.has(key)).sort(),
+    incomplete: [
+      ...incompleteEntries(registry.missingTools),
+      ...incompleteEntries(registry.contractLag),
+    ].sort(),
+  };
+}