@rt-tools/agent-kit 0.8.2 → 0.9.0

package/assets/checks/spec-anchors.mjs

@@ -0,0 +1,297 @@
+/**
+ * Привязка правила к коду и законы, которые применяет спек.
+ *
+ * Правило живёт в спеке, привязка — в компаньоне рядом; ключ связи — сам текст правила.
+ * Здесь же разбирается мёртвая привязка: символ, объявленный в своём файле и больше нигде не
+ * встречающийся, местом исполнения правила не считается.
+ */
+import {
+    ANCHOR,
+    BACKTICKED,
+    CONSTITUTION_DIR,
+    SOURCE_ROOTS,
+    VERDICT,
+    VERDICT_MIN,
+    bulletsOf,
+    exists,
+    read,
+    report,
+    sectionOf,
+    walk,
+} from './spec-common.mjs';
+
+// ── 1. Якоря правил ────────────────────────────────────────────────────────────
+
+const escapeForRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
+
+/**
+ * Символ ищется как слово: подстрока дала бы ложное совпадение на префиксе.
+ *
+ * Границы слова считаются буквой любого алфавита, а не `\b`: он в JavaScript знает буквой
+ * только латиницу, и `\bСемья\b` не совпадает ни разу — привязка на русском слове читалась
+ * как ведущая в файл, где этого слова нет, при том что слово стоит там первой же строкой.
+ */
+function fileHasSymbol(path, symbol) {
+    // Дефис здесь не экранируется: вне класса символов он ничего не значит, а под флагом `u`
+    // лишнее экранирование — уже отказ разбора. Общий экранировщик его защищает, потому что
+    // рассчитан и на класс тоже, и `task-flow` роняло всю сверку целиком.
+    const word = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?<![\\p{L}\\p{N}_])${word}(?![\\p{L}\\p{N}_])`, 'u').test(read(path));
+}
+
+/**
+ * Привязки, у которых остаётся выяснить, зовёт ли символ хоть кто-нибудь. Копятся
+ * в один список и разбираются одним проходом по исходникам: обходить `apps` и
+ * `libs` на каждую из пятисот привязок было бы полтысячи обходов.
+ */
+const traced = [];
+
+/** Жирное начало пункта — ключ, по которому правило находит свою строку привязки. */
+function ruleHeadOf(bulletText) {
+    const bold = bulletText.match(/\*\*(.+?)\*\*/s);
+
+    return bold ? bold[1].replace(/\s+/g, ' ').trim() : null;
+}
+
+/**
+ * Правила живут в `spec.md`, привязка к коду — в `implementation.md` рядом. Разделены
+ * потому, что спек описывает продукт и читается без знания устройства, а привязка
+ * устаревает при каждом переименовании.
+ *
+ * Ключ связи — сам текст правила, а не отдельный идентификатор: тогда правку формулировки
+ * невозможно сделать, забыв про привязку, — строка перестанет находиться.
+ *
+ * Заголовок раздела приходит доводом: у спека это `## Правила`, у закона — `## Статьи`.
+ * Одно слово в двух смыслах развели именно здесь: «правило» — слой между законом и скилом,
+ * а внутри закона живут статьи.
+ */
+/**
+ * Строки таблицы привязок компаньона.
+ *
+ * Компаньон правила держит три таблицы: чем вещи правила названы в этом дереве, где лежат
+ * механизмы и где исполняется каждая статья. Привязки — только третья, и берётся она по имени
+ * раздела, а не по месту в файле. Пока читался весь файл, строки первых двух попадали в список
+ * наравне с настоящими и тут же объявлялись расхождением: статьи с таким текстом в правиле нет
+ * и быть не может. Две трети перечня в дереве были ими, и правильно дописанная строка «Где это
+ * лежит» отвечала отказом.
+ *
+ * У компаньона спека домена раздела нет: там таблица одна, и сужать нечего — такой зовёт без
+ * имени раздела. У правила раздел стоит в образце компаньона, поэтому его отсутствие — отказ:
+ * молча прочесть вместо него весь файл значило бы вернуть тот же дефект.
+ */
+function rowsOfMap(specFile, mapFile, mapHeading) {
+    const text = read(mapFile);
+    if (!mapHeading) {
+        return text.split('\n');
+    }
+    const section = sectionOf(text, mapHeading);
+    if (!section.length) {
+        report(mapFile, `нет раздела \`${mapHeading}\` — привязкам правила негде лежать`);
+    }
+
+    return section;
+}
+
+function checkRuleImplementation(specFile, text, mapFile, heading = '## Правила', mapHeading = '') {
+    const bullets = bulletsOf(sectionOf(text, heading));
+    if (!bullets.length) {
+        report(specFile, `в разделе \`${heading}\` нет ни одного пункта`);
+
+        return;
+    }
+
+    if (!exists(mapFile)) {
+        report(specFile, `нет файла \`${mapFile.split('/').pop()}\` рядом — правилам не к чему привязаться`);
+
+        return;
+    }
+
+    const rows = new Map();
+    for (const line of rowsOfMap(specFile, mapFile, mapHeading)) {
+        const cells = line.match(/^\|([^|]+)\|([^|]*)\|\s*$/);
+        if (!cells) {
+            continue;
+        }
+        const head = cells[1].replace(/\s+/g, ' ').trim();
+        // Шапка таблицы: у спека колонка называется «Правило», у закона — «Статья».
+        if (!head || head === 'Правило' || head === 'Статья' || /^-+$/.test(head)) {
+            continue;
+        }
+        const cell = cells[2].trim();
+        rows.set(head, {
+            anchors: [...cells[2].matchAll(ANCHOR)],
+            verdict: VERDICT.test(cell) && cell.length >= VERDICT_MIN,
+            used: false,
+        });
+    }
+
+    for (const bullet of bullets) {
+        const head = ruleHeadOf(bullet.text);
+        if (!head) {
+            report(specFile, `правило без жирного начала: «${bullet.text.replace(/^-\s+/, '').slice(0, 60)}…»`);
+            continue;
+        }
+        const row = rows.get(head);
+        if (!row) {
+            report(
+                mapFile,
+                `правило без привязки: «${head.slice(0, 60)}…» — допиши строку с \`файл:символ\`, ` +
+                    'вердиктом «Не исполняется» с причиной либо перенеси правило в «Открытые вопросы» как Q-N'
+            );
+            continue;
+        }
+        row.used = true;
+        if (!row.anchors.length && !row.verdict) {
+            report(
+                mapFile,
+                `у правила «${head.slice(0, 60)}…» пустая привязка — поставь \`файл:символ\` ` +
+                    'либо вердикт «Не исполняется», «Не применимо», «Не проверяется» с причиной'
+            );
+        }
+        for (const [, path, symbol] of row.anchors) {
+            if (!exists(path)) {
+                report(mapFile, `привязка ведёт в никуда: нет файла \`${path}\``);
+            } else if (!fileHasSymbol(path, symbol)) {
+                report(mapFile, `привязка не сходится: в \`${path}\` нет \`${symbol}\``);
+            } else {
+                traced.push({ mapFile, path, symbol });
+            }
+        }
+    }
+
+    // Обратная сторона: строка, под которой правила больше нет, — след переименования.
+    // Без неё привязка копится и начинает описывать несуществующие обещания
+    for (const [head, row] of rows) {
+        if (!row.used) {
+            report(mapFile, `привязка без пункта: «${head.slice(0, 60)}…» — в \`${specFile}\` такого пункта нет`);
+        }
+    }
+}
+
+// ── 5. Мёртвые привязки ───────────────────────────────────────────────────────
+
+/**
+ * Код без комментариев. Упоминание символа в пояснении вызовом не является, а
+ * пояснений у мёртвого кода как раз обычно больше, чем у живого.
+ */
+const codeOf = (text) => text.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:`'"])\/\/.*$/gm, '$1');
+
+const DECLARATION_MODIFIERS = '(?:export|declare|abstract|public|private|protected|static|readonly|override|async|accessor)';
+
+/**
+ * Объявлен ли символ здесь. Проверка идёт только по объявлениям: привязка к
+ * чужому полю (`HttpStatus.SERVICE_UNAVAILABLE`), ключу словаря или содержимому
+ * строки законна и встречается ровно один раз по своей природе.
+ */
+function fileDeclaresSymbol(code, symbol) {
+    const escaped = escapeForRegExp(symbol);
+
+    return (
+        new RegExp(`\\b(?:const|let|var|function|class|interface|type|enum)\\s+${escaped}\\b`).test(code) ||
+        new RegExp(`^\\s*(?:${DECLARATION_MODIFIERS}\\s+)*#?${escaped}\\s*[(<:=]`, 'm').test(code)
+    );
+}
+
+/**
+ * Файлы, в которых встречается каждый символ. Дефис берётся в токен целиком ради
+ * атрибутов разметки, а части такого токена добавляются отдельно: иначе
+ * `resolving` внутри `data-resolving` перестал бы находиться.
+ */
+function symbolOwners() {
+    const owners = new Map();
+    const remember = (token, file) => {
+        let files = owners.get(token);
+        if (!files) {
+            files = new Set();
+            owners.set(token, files);
+        }
+        files.add(file);
+    };
+
+    for (const file of SOURCE_ROOTS.flatMap((root) => walk(root, (name) => name.endsWith('.ts') || name.endsWith('.html')))) {
+        const text = file.endsWith('.ts') ? codeOf(read(file)) : read(file);
+        for (const [token] of text.matchAll(/[A-Za-z_][\w-]*/g)) {
+            remember(token, file);
+            if (token.includes('-')) {
+                token.split('-').forEach((part) => part && remember(part, file));
+            }
+        }
+    }
+
+    return owners;
+}
+
+/**
+ * Символ, объявленный в своём файле и больше нигде не встречающийся, ничего не
+ * исполняет: правило, привязанное к нему, описывает намерение.
+ */
+function checkTracedAnchors() {
+    const code = new Map();
+    const codeAt = (path) => {
+        if (!code.has(path)) {
+            code.set(path, codeOf(read(path)));
+        }
+
+        return code.get(path);
+    };
+
+    const declared = traced.filter(({ path, symbol }) => path.endsWith('.ts') && fileDeclaresSymbol(codeAt(path), symbol));
+    if (!declared.length) {
+        return;
+    }
+
+    const owners = symbolOwners();
+    for (const { mapFile, path, symbol } of declared) {
+        const here = (codeAt(path).match(new RegExp(`\\b${escapeForRegExp(symbol)}\\b`, 'g')) || []).length;
+        const elsewhere = [...(owners.get(symbol) || [])].filter((file) => file !== path).length;
+        if (here + elsewhere < 2) {
+            report(
+                mapFile,
+                `привязка ведёт в мёртвый код: \`${symbol}\` объявлен в \`${path}\` и больше нигде не встречается — ` +
+                    'либо правило исполняется в другом месте, либо ему место в «Открытых вопросах» как Q-N'
+            );
+        }
+    }
+}
+
+// ── 1a. Законы, которые применяет спек ────────────────────────────────────────
+
+/**
+ * Связь «закон — правило» и «правило — паттерн» сверяется в обе стороны, а спек до сих пор
+ * говорил только о домене. Закон при этом он применял: ссылки на `docs/constitution/…`
+ * лежали внутри строки зависимостей и посреди текста, и по закону нельзя было узнать, какие
+ * домены на нём стоят, — только грепом.
+ *
+ * Отсюда строка `**Законы:**` в шапке и сверка обеих сторон: закон, названный в тексте, но не
+ * объявленный, и объявленный закон, которого нет.
+ */
+const SPEC_LAWS = /^\*\*Законы:\*\*\s*(.+)$/;
+/**
+ * Ссылка на закон где угодно в тексте спека — по ней считается вторая сторона связи. Слой в
+ * пути необязателен: законы приложения лежат в `application/`, а называются так же.
+ */
+const LAW_REFERENCE = new RegExp(`\`${CONSTITUTION_DIR}/(?:application/)?([a-z-]+)\\.md\``, 'g');
+
+function checkSpecLaws(file, text, laws) {
+    const line = text.split('\n').find((candidate) => SPEC_LAWS.test(candidate));
+    if (!line) {
+        report(file, 'в шапке нет строки `**Законы:**` — не видно, какие законы домен применяет');
+
+        return;
+    }
+
+    const declared = new Set([...line.match(SPEC_LAWS)[1].matchAll(BACKTICKED)].map(([, name]) => name));
+    for (const name of declared) {
+        if (!laws.has(name)) {
+            report(file, `в строке \`**Законы:**\` назван \`${name}\`, а закона с таким именем нет ни в одном слое`);
+        }
+    }
+
+    for (const [, name] of text.matchAll(LAW_REFERENCE)) {
+        if (!declared.has(name)) {
+            report(file, `закон \`${name}\` назван в тексте, но не объявлен в строке \`**Законы:**\``);
+        }
+    }
+}
+
+export { checkRuleImplementation, checkSpecLaws, checkTracedAnchors };

package/assets/checks/spec-common.mjs

@@ -0,0 +1,222 @@
+/**
+ * Общее для всех предметов сверки спеков: что считается доменом, чем читается дерево и чем
+ * режется документ на разделы и пункты.
+ *
+ * Модуль назван не `check-*`, и это не украшение: умолчание пакета собирает набор гейта пуша
+ * перебором имён `check-<что>.mjs` в каталоге проверок, и помощник с таким именем гейт стал бы
+ * гонять как отдельную проверку.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CONFIG, ROOT } from './rt-kit-checks.config.mjs';
+
+const SPECS_DIR = CONFIG.specsDir;
+const CONSTITUTION_DIR = 'docs/constitution';
+/**
+ * Каталоги под `docs/specs`, доменами не являющиеся: шаблон содержит образцы с
+ * плейсхолдерами, и обязательных разделов у них нет.
+ */
+const NOT_DOMAINS = ['_template'];
+/**
+ * Где ищутся тесты. Берётся из настройки дерева, а не из кода: зашитые здесь корни молча не
+ * находили ни одного теста у дерева, которое держит код иначе, — и каждый сценарий выглядел
+ * непокрытым, притом что тест на него был.
+ */
+const TEST_ROOTS = CONFIG.sourceRoots;
+/** Где ищется вызов символа из привязки. */
+const SOURCE_ROOTS = [...CONFIG.sourceRoots, ...(CONFIG.schemaFile ? [CONFIG.schemaFile.split('/')[0]] : [])];
+const SKIPPED_DIRS = CONFIG.skippedDirs;
+
+/**
+ * `### SC-BK-03 — заявка на занятые даты`
+ *
+ * Номер принимается от одной цифры до трёх. Заголовок, не подошедший под шаблон, сценария не
+ * заводит и отказа не даёт: дерево, пронумеровавшее сценарии с единицы, теряло бы первые
+ * девять из них молча — ни в покрытии, ни в долгах, при зелёной сверке.
+ */
+const SCENARIO_HEADING = /^###\s+(SC-([A-Z]{2,4})-(\d{1,3}))\s+—\s+(.+?)\s*$/;
+/** Отметка осознанно непокрытого сценария; причина обязательна */
+const UNCOVERED = /^Не покрыто:\s*\S/;
+/** Тест есть, но проверяет не всё обещанное или идёт другим путём */
+const PARTIAL = /^Покрытие:\s*частичное\s*—\s*\S/;
+/** Упоминание сценария в заголовке теста; номер той же длины, что и в заголовке сценария */
+const SCENARIO_REFERENCE = /\bSC-[A-Z]{2,4}-\d{1,3}\b/g;
+/** Строка обещания сценария; её продолжения идут с отступом */
+const PROMISE = /^Тогда\s+\S/;
+/**
+ * Человек перед экраном и его восприятие. Границы слова не ставятся: `\b` в JavaScript
+ * считает буквой только латиницу, и `\bгость\b` не совпал бы ни разу.
+ */
+const ACTOR = /(гост[ьяию]|владел(?:ец|ьца|ьцу|ьцем)|сотрудник\w*|оператор\w*|пользовател\w+)/i;
+const PERCEIVES = /(вид(?:ит|ят|но)|чита(?:ет|ют)|смотр(?:ит|ят))/i;
+/** Сквозные тесты: только они идут тем же путём, что пользователь */
+const E2E_ROOTS = CONFIG.e2eRoots;
+
+/**
+ * Якорь правила: `путь/к/файлу.ts:символ` в обратных кавычках. Расширение до восьми
+ * букв — иначе `schema.prisma` не считается путём, и правило про умолчание колонки
+ * выглядит как правило без якоря. Заглавные и десять букв нужны ради `api.Dockerfile`:
+ * без них правило про режим исполнения образа считалось правилом с пустой привязкой,
+ * а привязать его больше не к чему — режим объявлен ровно там.
+ *
+ * Символ — любая буква, а не только латинская: тексты, которые исполняет модель, написаны
+ * своим языком, и латиницей в них называется ровно то, что утверждения не держит — имя поля
+ * шапки, имя инструмента. Привязанное к имени поля утверждение остаётся зелёным, когда текст
+ * переписан целиком. Алфавит не перечисляется диапазонами: перечисленные молча не покрывают
+ * соседнего, и промах выглядит отсутствием привязки. Путь при этом остаётся латинским — он
+ * адрес в дереве, а не слово текста.
+ */
+const ANCHOR = /`([\w./-]+\.[A-Za-z]{2,10}):(\p{L}[\p{L}\p{N}_-]*|_[\w-]*)`/gu;
+/**
+ * Явный вердикт вместо якоря: статья, которой в дереве исполняться негде. Так бывает
+ * законно — правило говорит о службе, которой дерево не держит, или о движении человека,
+ * до которого проверке не дотянуться: кнопку слияния нажимают в браузере, где хуков нет
+ * вовсе. Якорь такой статье можно поставить только в файл, который её не исполняет, —
+ * проверка примет, а читателю совратёт.
+ *
+ * Принимается вердикт с причиной, а не одно слово: пустой он становится способом закрыть
+ * любую строку, и таблица за месяц превращается в список отговорок. Порог длины — та же
+ * мера, что у обхода гарда документов: причина короче его причиной не считается.
+ *
+ * Конец слова ищется отрицательным просмотром, а не `\b`: границей слова JavaScript знает
+ * только латиницу, и после кириллической буквы её нет вовсе — вердикт не опознавался ни
+ * разу.
+ */
+const VERDICT = /^\s*(?:\*\*)?Не (?:исполняется|применимо|проверяется)(?![\p{L}\p{N}_])/u;
+const VERDICT_MIN = 40;
+/** Строка шапки, объявляющая либы, чьи процедуры домен обслуживает */
+const PROCEDURE_ROOTS = /^\*\*Процедуры:\*\*\s*(.+)$/;
+const BACKTICKED = /`([^`]+)`/g;
+
+const REQUIRED_HEADINGS = [
+    '## Зачем',
+    '## Терминология',
+    '### Как это называется в интерфейсе',
+    '## Правила',
+    '## Что не входит',
+    '## Контракт',
+    '### Коды отказов',
+    '## Данные',
+    '## Экраны и состояния',
+    '## Сквозные требования',
+    '### Локали',
+    '### SEO',
+    '### Мобильная раскладка',
+    '### Мультиобъектность',
+    '## Решения',
+    '## Открытые вопросы',
+    '## История изменений',
+];
+
+const problems = [];
+const report = (where, message) => problems.push(`${where}: ${message}`);
+
+function walk(dir, accept) {
+    const found = [];
+    let entries;
+    try {
+        entries = readdirSync(join(ROOT, dir), { withFileTypes: true });
+    } catch {
+        return found;
+    }
+
+    for (const entry of entries) {
+        const path = `${dir}/${entry.name}`;
+        if (entry.isDirectory()) {
+            if (!SKIPPED_DIRS.includes(entry.name)) {
+                found.push(...walk(path, accept));
+            }
+        } else if (accept(entry.name)) {
+            found.push(path);
+        }
+    }
+
+    return found;
+}
+
+const read = (path) => readFileSync(join(ROOT, path), 'utf8');
+const exists = (path) => existsSync(join(ROOT, path));
+
+/** Директории доменов: `docs/specs/<домен>`, кроме шаблона. */
+function collectDomains() {
+    try {
+        return readdirSync(join(ROOT, SPECS_DIR), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !NOT_DOMAINS.includes(entry.name))
+            .map((entry) => entry.name);
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Строки раздела: от его заголовка до следующего заголовка того же или более
+ * высокого уровня. Подразделы в раздел входят — «Коды отказов» разбираются
+ * отдельно, но остаются частью «Контракта».
+ */
+function sectionOf(text, heading) {
+    const level = heading.match(/^#+/)[0].length;
+    const lines = text.split('\n');
+    const start = lines.findIndex((line) => line.trimEnd() === heading);
+    if (start < 0) {
+        return [];
+    }
+    const rest = lines.slice(start + 1);
+    const end = rest.findIndex((line) => {
+        const marks = line.match(/^(#+)\s/);
+
+        return marks && marks[1].length <= level;
+    });
+
+    return end < 0 ? rest : rest.slice(0, end);
+}
+
+/** Пункты списка верхнего уровня вместе с их продолжениями. */
+function bulletsOf(lines) {
+    const bullets = [];
+    for (const [index, line] of lines.entries()) {
+        if (/^-\s+\S/.test(line)) {
+            bullets.push({ line: index, text: line });
+        } else if (bullets.length && /^\s+\S/.test(line)) {
+            bullets[bullets.length - 1].text += ` ${line.trim()}`;
+        } else if (!line.trim()) {
+            continue;
+        } else if (/^[#|]/.test(line)) {
+            // таблица или заголовок — список кончился
+            break;
+        }
+    }
+
+    return bullets;
+}
+
+export {
+    SPECS_DIR,
+    CONSTITUTION_DIR,
+    NOT_DOMAINS,
+    TEST_ROOTS,
+    SOURCE_ROOTS,
+    SKIPPED_DIRS,
+    SCENARIO_HEADING,
+    UNCOVERED,
+    PARTIAL,
+    SCENARIO_REFERENCE,
+    PROMISE,
+    ACTOR,
+    PERCEIVES,
+    E2E_ROOTS,
+    ANCHOR,
+    VERDICT,
+    VERDICT_MIN,
+    PROCEDURE_ROOTS,
+    BACKTICKED,
+    REQUIRED_HEADINGS,
+    problems,
+    report,
+    walk,
+    read,
+    exists,
+    collectDomains,
+    sectionOf,
+    bulletsOf,
+};

package/assets/checks/spec-contract.mjs

@@ -0,0 +1,152 @@
+/**
+ * Контракт спека против того, что объявлено в коде: таблица процедур — против декораторов,
+ * коды отказов — против точек броска.
+ */
+import { BACKTICKED, PROCEDURE_ROOTS, bulletsOf, read, report, sectionOf, walk } from './spec-common.mjs';
+
+// ── 2. Контракт против декораторов ────────────────────────────────────────────
+
+/** Корни либ, чьи процедуры домен обслуживает; объявлены в шапке спека. */
+function procedureRootsOf(text) {
+    const line = text.split('\n').find((candidate) => PROCEDURE_ROOTS.test(candidate));
+    if (!line) {
+        return null;
+    }
+    const value = line.match(PROCEDURE_ROOTS)[1];
+    if (/^\s*нет\s*$/i.test(value.replace(/[`.]/g, ''))) {
+        return [];
+    }
+
+    return [...value.matchAll(BACKTICKED)].map(([, path]) => path);
+}
+
+/** Что объявлено в самих процедурах: метод контракта и право на него. */
+function declaredProcedures(roots) {
+    const found = new Map();
+    for (const root of roots) {
+        for (const file of walk(root, (name) => name.endsWith('.procedure.ts'))) {
+            const text = read(file);
+            const method = text.match(/\.method\.([A-Za-z_]\w*)/);
+            if (!method) {
+                continue;
+            }
+            const service = text.match(/typeof\s+(\w+)\.method\./);
+            const required = text.match(/@RequiresPermission\(\s*'([^']+)'/);
+            const isPublic = /@PublicProcedure\(/.test(text);
+            found.set(method[1].toLowerCase(), {
+                file,
+                method: method[1],
+                service: service ? service[1] : '',
+                permission: required ? required[1] : isPublic ? 'публично' : '',
+            });
+        }
+    }
+
+    return found;
+}
+
+/** Строки таблицы «Контракта»: первая ячейка — процедура, вторая — право. */
+function contractRows(text) {
+    const rows = [];
+    for (const [index, line] of sectionOf(text, '## Контракт').entries()) {
+        if (!line.startsWith('|') || /^\|[\s:|-]+\|$/.test(line)) {
+            continue;
+        }
+        const cells = line
+            .split('|')
+            .slice(1, -1)
+            .map((cell) => cell.trim());
+        if (cells.length < 2) {
+            continue;
+        }
+        const name = (cells[0].match(/`([^`]+)`/) || [])[1];
+        if (!name) {
+            continue;
+        }
+        const permission = (cells[1].match(/`([^`]+)`/) || [])[1] || cells[1];
+        rows.push({ line: index, name, permission: permission.trim(), short: name.split('.').pop() });
+    }
+
+    return rows;
+}
+
+function checkContract(file, text, roots) {
+    if (roots === null) {
+        report(file, 'в шапке нет строки `**Процедуры:**` — нечем сверить таблицу «Контракта» с декораторами');
+
+        return;
+    }
+    const declared = declaredProcedures(roots);
+    const rows = contractRows(text);
+    const described = new Set();
+
+    for (const row of rows) {
+        const found = declared.get(row.short.toLowerCase());
+        if (!found) {
+            report(file, `в «Контракте» есть \`${row.name}\`, но процедуры с таким методом в ${roots.join(', ')} нет`);
+            continue;
+        }
+        described.add(row.short.toLowerCase());
+        if (found.permission && row.permission !== found.permission) {
+            report(
+                file,
+                `право у \`${row.name}\` разошлось: в спеке «${row.permission}», ` + `в \`${found.file}\` объявлено «${found.permission}»`
+            );
+        }
+    }
+
+    for (const [key, found] of declared) {
+        if (!described.has(key)) {
+            report(
+                file,
+                `процедура \`${found.service}.${found.method}\` (${found.file}) домену принадлежит, ` + 'но в таблице «Контракта» её нет'
+            );
+        }
+    }
+}
+
+// ── 3. Коды отказов ───────────────────────────────────────────────────────────
+
+function checkRefusalCodes(file, text, roots) {
+    const section = sectionOf(text, '### Коды отказов');
+    const bullets = bulletsOf(section);
+    /**
+     * «Не применимо» — законный ответ и здесь. Домен, у которого есть процедуры,
+     * но нет ни одного `Code.X`, иначе не описывался вовсе: пустой раздел
+     * проверка отвергает, а любой выписанный код отвергает тем более — бросать
+     * его в домене некому. Так живёт проверка живости: отказ она подаёт кодом
+     * ответа, а не отказом процедуры.
+     */
+    // Без `\b`: кириллица не входит в `\w`, и границы слова после «применимо» не возникает
+    const notApplicable = section.some((line) => /^Не применимо/.test(line.trim()));
+    if (!bullets.length) {
+        if (!notApplicable) {
+            report(file, 'в разделе `### Коды отказов` нет ни одного кода и нет ответа «Не применимо»');
+        }
+
+        return;
+    }
+    if (!roots || !roots.length) {
+        return;
+    }
+    const sources = roots.flatMap((root) => walk(root, (name) => name.endsWith('.ts') && !name.endsWith('.spec.ts')));
+    const thrown = new Set();
+    for (const source of sources) {
+        for (const [, code] of read(source).matchAll(/\bCode\.([A-Za-z]\w*)/g)) {
+            thrown.add(code);
+        }
+    }
+
+    for (const bullet of bullets) {
+        const code = (bullet.text.match(/`([A-Za-z]\w*)`/) || [])[1];
+        if (!code) {
+            report(file, `в «Кодах отказов» строка без кода в кавычках: «${bullet.text.slice(0, 60)}…»`);
+            continue;
+        }
+        if (!thrown.has(code)) {
+            report(file, `код отказа \`${code}\` в домене нигде не бросается — либо он не отсюда, либо путь его не даёт`);
+        }
+    }
+}
+
+export { checkContract, checkRefusalCodes, procedureRootsOf };