@rt-tools/agent-kit 0.3.0 → 0.5.0

package/assets/checks/check-reuse.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * Сплошная проверка того, что готовое не обошли.
+ *
+ * Гард `reuse-first-guard.sh` судит правку в момент, когда её пишут, и знает только
+ * добавленный текст. Написанное до него не считает никто: проверка стилей меряет классы,
+ * линтеры — типы и приёмы, а то, что экран собран нативной кнопкой вместо кнопки кита, не
+ * видно ни одному из них. Эта проверка отвечает на другой вопрос — «а сколько такого в
+ * дереве сейчас», — и потому смотрит на файл целиком, а не на правку.
+ *
+ * Признаки те же, что у гарда, и берутся оттуда же: расходиться им нельзя, иначе правка
+ * проходит гард и падает на гейте. Отличий два. Первое: инвентарь кита не читается — гард
+ * спрашивает диск, потому что отвечает одной правке, а сплошной проверке важно накопленное,
+ * и пропавший пакет молча обнулял бы сводку. Второе: маркер `native-ok` снимает свою
+ * строку, а не весь файл.
+ *
+ * Накопленное к моменту заведения проверки лежит в tools/reuse-allowlist.json и отказом не
+ * считается: гейт падает на новом расхождении, а старое остаётся видимым числом в сводке.
+ * Снимок списка — `node tools/check-reuse.mjs --baseline`.
+ *
+ * Ненулевой код возврата и перечень расхождений.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { allowlistOf, CONFIG, ROOT } from './rt-kit-checks.config.mjs';
+
+const ALLOWLIST = allowlistOf('reuse');
+const SOURCE_ROOTS = CONFIG.sourceRoots;
+const SKIPPED_DIRS = CONFIG.skippedDirs;
+const BACKEND_ROOTS = CONFIG.backendRoots;
+
+/**
+ * Признак расхождения: чем он виден в тексте и на что готовое его меняет. Порядок строк —
+ * порядок в сводке, поэтому родственные признаки стоят рядом.
+ */
+const SIGNALS = [
+    {
+        key: 'input',
+        ext: '.html',
+        find: (text) => count(text, /<input\b/g),
+        instead: 'rt-input / rt-input-number / rt-checkbox / rt-file-input',
+    },
+    { key: 'textarea', ext: '.html', find: (text) => count(text, /<textarea\b/g), instead: 'rt-textarea' },
+    { key: 'select', ext: '.html', find: (text) => count(text, /<select\b/g), instead: 'rt-select / rt-multiselect' },
+    {
+        key: 'button',
+        ext: '.html',
+        find: (text) => count(withoutKitButtons(text), /<button\b/g),
+        instead: 'button[rtButton] / rt-icon-button',
+    },
+    { key: 'table', ext: '.html', find: (text) => count(text, /<table\b/g), instead: 'rt-table' },
+    { key: 'dialog', ext: '.html', find: (text) => count(text, /<dialog\b/g), instead: 'rt-dialog' },
+    { key: 'alert', ext: '.html', find: (text) => count(text, /role="alert"/g), instead: 'rt-message' },
+
+    { key: 'overlay', ext: '.scss', find: fullScreenOverlays, instead: 'rt-dialog / rt-aside / rt-bottom-sheet' },
+    {
+        key: 'backdrop',
+        ext: '.scss',
+        find: (text) => count(text, /backdrop-filter|background(-color)?: *(rgba\( *0 *, *0 *, *0|rgb\( *0 +0 +0)/g),
+        instead: 'backdrop рисует rt-dialog',
+    },
+    { key: 'z-index', ext: '.scss', find: (text) => count(text, /z-index: *\d{4,}/g), instead: 'слой оверлеев кита уже выше' },
+    { key: 'spin', ext: '.scss', find: (text) => count(text, /@keyframes[^{]*(spin|rotate|loading)/g), instead: 'rt-spinner' },
+    {
+        key: 'shimmer',
+        ext: '.scss',
+        find: (text) => count(text, /@keyframes[^{]*(shimmer|skeleton|pulse)/g),
+        instead: 'rt-skeleton / rt-skeleton-wrapper',
+    },
+
+    { key: 'inline-template', ext: '.component.ts', find: (text) => count(text, /^ *template: *['"`]/gm), instead: 'шаблон в своём .html' },
+    // Список стилей открывается своей строкой, а строка с кавычкой идёт следующей
+    {
+        key: 'inline-styles',
+        ext: '.component.ts',
+        find: (text) => count(text, /^ *styles: *(\[\s*)?['"`\n]/gm),
+        instead: 'стили в своём .scss',
+    },
+    {
+        key: 'value-accessor',
+        ext: '.component.ts',
+        find: (text) => (/ControlValueAccessor|NG_VALUE_ACCESSOR/.test(text) && !/extends VmFormControlBase/.test(text) ? 1 : 0),
+        instead: 'VmFormControlBase',
+    },
+    {
+        key: 'mapper-base',
+        ext: '.mapper.ts',
+        // На бэкенде перевод сущности написан свободными функциями — это долг `Q-S-1`,
+        // а не место для этой проверки. Где лежит бэкенд, знает настройка дерева: зашитый здесь
+        // корень молча проверял бы фронтовым мерилом чужой код у всякого, кто держит его иначе.
+        skip: (path) => BACKEND_ROOTS.some((root) => path.startsWith(root)),
+        find: (text) => (/class +[A-Za-z0-9_]+Mapper/.test(text) && !/extends BaseMapper/.test(text) ? 1 : 0),
+        instead: 'BaseMapper и this.typeCast',
+    },
+    {
+        key: 'procedure-mark',
+        ext: '.procedure.ts',
+        find: (text) => (/export class/.test(text) && !/@ConnectProcedure/.test(text) ? 1 : 0),
+        instead: '@ConnectProcedure()',
+    },
+    {
+        key: 'aside-base',
+        ext: '.component.ts',
+        onlyNamed: /aside[^/]*\.component\.ts$/,
+        find: (text) => (/export class/.test(text) && !/extends VmRouteAsideComponent/.test(text) ? 1 : 0),
+        instead: 'VmRouteAsideComponent',
+    },
+];
+
+function count(text, expression) {
+    return [...text.matchAll(expression)].length;
+}
+
+/** `button[rtButton]` — предписанный вариант, а подстрока `<button` у него та же */
+function withoutKitButtons(text) {
+    return text.replace(/<button\b[^>]*rtButton[^>]*>/gs, '');
+}
+
+/** Хост, растянутый на весь экран: `inset: 0` либо все четыре стороны в нуле */
+function fullScreenOverlays(text) {
+    if (!/position: *fixed/.test(text)) {
+        return 0;
+    }
+    const stretched =
+        /inset: *0/.test(text) ||
+        (/(^|[^-])top: *0/.test(text) && /left: *0/.test(text) && /right: *0/.test(text) && /bottom: *0/.test(text));
+
+    return stretched ? 1 : 0;
+}
+
+function collectFiles(dir) {
+    const files = [];
+    for (const entry of readdirSync(join(ROOT, dir), { withFileTypes: true })) {
+        if (SKIPPED_DIRS.includes(entry.name)) {
+            continue;
+        }
+        const path = `${dir}/${entry.name}`;
+        if (entry.isDirectory()) {
+            files.push(...collectFiles(path));
+        } else if (/\.(html|scss|ts)$/.test(entry.name)) {
+            files.push(path);
+        }
+    }
+
+    return files;
+}
+
+/** Тесты, storybook и сквозные тесты не судятся: там нативное уместно */
+function judged(path) {
+    return !/\.stories\.(ts|html)$|\.spec\.ts$|\/site-e2e\/|\/admin-e2e\//.test(path);
+}
+
+/**
+ * Строка с маркером — осознанное отступление, названное автором. Снимается только она сама:
+ * весь файл маркер не гасит, иначе один разрешённый случай прикрывал бы соседние.
+ */
+function withoutMarked(text) {
+    return text
+        .split('\n')
+        .filter((line) => !line.includes('native-ok'))
+        .join('\n');
+}
+
+const allowlist = JSON.parse(readFileSync(join(ROOT, ALLOWLIST), 'utf8'));
+const known = new Set([...(allowlist.accepted ?? []), ...(allowlist.debt ?? [])]);
+const debt = new Set(allowlist.debt ?? []);
+
+const findings = [];
+for (const root of SOURCE_ROOTS) {
+    for (const path of collectFiles(root).filter(judged).sort()) {
+        const text = withoutMarked(readFileSync(join(ROOT, path), 'utf8'));
+        for (const signal of SIGNALS) {
+            if (!path.endsWith(signal.ext) || signal.skip?.(path) || (signal.onlyNamed && !signal.onlyNamed.test(path))) {
+                continue;
+            }
+            const found = signal.find(text);
+            if (found > 0) {
+                findings.push({ key: `${signal.key} ×${found} @ ${path}`, instead: signal.instead });
+            }
+        }
+    }
+}
+
+const fresh = findings.filter((finding) => !known.has(finding.key));
+const stale = [...known].filter((key) => !findings.some((finding) => finding.key === key));
+
+if (process.argv.includes('--baseline')) {
+    console.log(JSON.stringify({ ...allowlist, debt: findings.map((finding) => finding.key).sort() }, null, 4));
+    process.exit(0);
+}
+
+const problems = [
+    ...fresh.map((finding) => `${finding.key} — готовое: ${finding.instead}`),
+    ...stale.map((key) => `${key}: значится в ${ALLOWLIST}, а в дереве такого расхождения больше нет — строку поправить или убрать`),
+];
+
+if (problems.length > 0) {
+    console.error(`check-reuse: расхождений ${problems.length}\n`);
+    problems.forEach((problem) => console.error(`  ${problem}`));
+    console.error('\nПравило единообразия — скил `reuse-first`.');
+    process.exit(1);
+}
+
+const places = findings.reduce((sum, finding) => sum + Number(finding.key.match(/×(\d+)/)[1]), 0);
+console.log(
+    `check-reuse: мест, где готовое обошли, ${places} в ${findings.length} признаках — принято ${findings.length - debt.size}, долг ${debt.size}, новых нет`
+);

package/assets/checks/check-schema-drift.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Проверка того, что миграции и `prisma/schema.prisma` описывают одну и ту же базу.
+ *
+ * Расхождение между ними не видит ни линт, ни сборка: оно живёт не в коде, а между
+ * схемой и SQL. Так в главную ветку уехала миграция, создававшая два индекса,
+ * которых схема не объявляла, — выкатка упала уже в конвейере.
+ *
+ * Меряются именно миграции, а не база того, кто запускает проверку. База
+ * разработчика законно несёт след любой недоделанной ветки: одна такая держала
+ * пуш чужой правки четырьмя таблицами и восемью колонками, которых в схеме
+ * главной ветки нет, — при том что миграции со схемой сходились.
+ *
+ * Поэтому миграции накатываются на одноразовую теневую базу и сравнивается она.
+ * Теневая база заводится на каждый прогон и сносится после: оставленная между
+ * прогонами, она сама накопит след ветки с миграцией, и проверка снова начнёт
+ * судить о состоянии машины вместо репозитория.
+ *
+ * Ненулевой код возврата и объяснение расхождения.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { CONFIG, ROOT } from './rt-kit-checks.config.mjs';
+
+/** Суффикс теневой базы: по нему видно, что сносится именно она, а не чья-то рабочая */
+const SHADOW_SUFFIX = '_gate_shadow';
+
+/**
+ * Признаки боевой базы — те же, что у `sql-guard`. Схема на проде меняется только
+ * выкаткой, и проверка туда не ходит ни читать, ни писать.
+ */
+const PRODUCTION_MARKS = CONFIG.productionMarks ?? [];
+
+/** Сервер жив, но базы нет; сервера нет вовсе — оба означают «проверять негде» */
+const SERVER_DOWN_CODES = ['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH', 'ETIMEDOUT'];
+
+function databaseUrl() {
+    if (process.env['DATABASE_URL']) {
+        return process.env['DATABASE_URL'];
+    }
+
+    const envFile = join(ROOT, '.env');
+    if (!existsSync(envFile)) {
+        return '';
+    }
+
+    const line = readFileSync(envFile, 'utf8')
+        .split('\n')
+        .find((row) => row.startsWith('DATABASE_URL='));
+
+    return line
+        ? line
+              .slice('DATABASE_URL='.length)
+              .trim()
+              .replace(/^["']|["']$/g, '')
+        : '';
+}
+
+/** Адрес теневой базы и адрес служебной, из которой она заводится и сносится */
+function shadowAddresses(url) {
+    const parsed = new URL(url);
+    const name = decodeURIComponent(parsed.pathname.replace(/^\//, ''));
+    const shadowName = `${name}${SHADOW_SUFFIX}`;
+
+    const shadow = new URL(url);
+    shadow.pathname = `/${encodeURIComponent(shadowName)}`;
+
+    // Завести и снести базу можно только из другой базы того же сервера; `postgres`
+    // есть всегда, а рабочая для этого не годится — снос идёт при живых к ней
+    // подключениях.
+    const service = new URL(url);
+    service.pathname = '/postgres';
+
+    return { shadowName, shadowUrl: shadow.toString(), serviceUrl: service.toString() };
+}
+
+function prisma(args, url) {
+    return spawnSync('npx', ['prisma', ...args], {
+        cwd: ROOT,
+        encoding: 'utf8',
+        env: { ...process.env, DATABASE_URL: url },
+    });
+}
+
+async function withServiceClient(serviceUrl, run) {
+    // Клиент базы подтягивается на месте, а не импортом сверху: дерево без хранилища этого
+    // пакета в зависимостях не держит, и статический импорт ронял бы проверку до того, как она
+    // успеет сказать, что сверять здесь нечего.
+    const pg = (await import('pg')).default;
+    const client = new pg.Client({ connectionString: serviceUrl });
+    try {
+        await client.connect();
+    } catch (error) {
+        // Погашенный докер — обычное состояние машины, а не повод не дать запушить
+        // документацию.
+        if (SERVER_DOWN_CODES.includes(error?.code)) {
+            console.log('check-schema-drift: база недоступна — сверять негде');
+
+            return 0;
+        }
+        throw error;
+    }
+
+    try {
+        return await run(client);
+    } finally {
+        await client.end();
+    }
+}
+
+async function main() {
+    if (!existsSync(join(ROOT, CONFIG.schemaFile))) {
+        console.log('check-schema-drift: схемы нет — сверять нечего');
+
+        return 0;
+    }
+
+    const url = databaseUrl();
+    if (!url) {
+        console.log('check-schema-drift: адрес базы не задан — сверять негде');
+
+        return 0;
+    }
+
+    if (PRODUCTION_MARKS.some((mark) => url.includes(mark))) {
+        console.log('check-schema-drift: адрес боевой — проверка туда не ходит');
+
+        return 0;
+    }
+
+    const { shadowName, shadowUrl, serviceUrl } = shadowAddresses(url);
+
+    return withServiceClient(serviceUrl, async (client) => {
+        // Идентификатор в кавычках: имя базы выведено из адреса, а не из текста запроса
+        const quoted = `"${shadowName.replace(/"/g, '""')}"`;
+        await client.query(`DROP DATABASE IF EXISTS ${quoted}`);
+
+        try {
+            // Базу заводит сам `migrate deploy`: своей команды создания не нужно
+            const deploy = prisma(['migrate', 'deploy'], shadowUrl);
+            if (deploy.status !== 0) {
+                console.error('check-schema-drift: миграции не накатываются на чистую базу\n');
+                console.error(`${deploy.stdout ?? ''}${deploy.stderr ?? ''}`);
+
+                return 1;
+            }
+
+            // `--exit-code`: 0 — расхождений нет, 2 — есть, прочее — сбой самой команды
+            const diff = prisma(
+                ['migrate', 'diff', '--from-config-datasource', '--to-schema', CONFIG.schemaFile, '--exit-code'],
+                shadowUrl
+            );
+            if (diff.status === 2) {
+                console.error('check-schema-drift: миграции и схема описывают разные базы\n');
+                console.error(`${diff.stdout ?? ''}${diff.stderr ?? ''}`);
+                console.error(
+                    '\nЛибо схема правлена без миграции, либо миграция создаёт то, чего схема не объявляет.\nКак писать миграцию — паттерн `git-workflow-migration`.'
+                );
+
+                return 1;
+            }
+            if (diff.status !== 0) {
+                console.log('check-schema-drift: сверка не отработала — пропущено');
+
+                return 0;
+            }
+
+            console.log('check-schema-drift: миграции и схема сошлись');
+
+            return 0;
+        } finally {
+            await client.query(`DROP DATABASE IF EXISTS ${quoted}`);
+        }
+    });
+}
+
+main().then(
+    (code) => process.exit(code),
+    (error) => {
+        // Сбой самой проверки пуш не держит: сломанная обвязка не должна мешать работать
+        console.log(`check-schema-drift: проверка не отработала (${error?.message ?? error}) — пропущено`);
+        process.exit(0);
+    }
+);