@rt-tools/agent-kit 0.8.3 → 0.9.0

package/assets/checks/check-styles.mjs

@@ -13,16 +13,25 @@
  * которого правило есть, но у чужого блока, — направление выбрано в сторону
  * ложных пропусков, а не ложных отказов.
  *
+ * Объявлением считается и то, что приехало подключённым пакетом: экран,
+ * собранный из готового, своих объявлений не держит вовсе. Читается ровно тот
+ * файл, который приложение назвало само, — обход односложный, и каталог
+ * зависимостей в корни исходников не попадает.
+ *
  * Динамическое `[rtElem]` не считается: имя там известно только в рантайме.
  *
  * Накопленное к моменту заведения проверки лежит в tools/styles-allowlist.json
  * и отказом не считается: гейт падает на НОВОМ классе без правила, а старое
- * остаётся видимым числом в сводке.
+ * остаётся видимым числом в сводке. Строка списка опознаётся по имени класса:
+ * перечень файлов при нём меняется от каждой правки разметки, и сверенный
+ * целиком он делал бы прежнюю строку лишней, а тот же самый долг — новым
+ * расхождением.
  *
  * Ненулевой код возврата и перечень расхождений.
  */
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, join } from 'node:path';
 
 import { allowlistOf, CONFIG, ROOT } from './rt-kit-checks.config.mjs';
 
@@ -33,11 +42,28 @@ const SKIPPED_DIRS = CONFIG.skippedDirs;
 const ELEM_RE = /rtElem="([a-z0-9-]+)"/g;
 /** Объявление элемента: и вложенное `&__item`, и полное `.<блок>__item` */
 const RULE_RE = /__([a-z0-9-]+)/g;
+/** Голова вложенности: строка, с которой начинается блок элемента */
+const HEAD_RE = /^&__([a-z0-9-]+)/;
+/** Колено вложенности: `&-<хвост>` внутри блока элемента дописывает имя, а не заводит своё */
+const TAIL_RE = /^&-([a-z0-9-]+)/;
+/** Подключение в файле стилей: `@use` и `@forward` берутся одним разбором */
+const USE_RE = /@(?:use|forward)\s+['"]([^'"]+)['"]/g;
+/** Строка списка известного: имя класса и перечень файлов при нём */
+const KEY_RE = /^elem (\S+) @ (.*)$/;
 
 const allowlist = JSON.parse(readFileSync(join(ROOT, ALLOWLIST), 'utf8'));
 const known = new Set([...(allowlist.accepted ?? []), ...(allowlist.debt ?? [])]);
 const debt = new Set(allowlist.debt ?? []);
 
+/** Строки списка по имени класса: перечень файлов в ключ входит, но сверяется отдельно */
+const knownByName = new Map();
+for (const key of known) {
+    const parsed = KEY_RE.exec(key);
+    if (parsed) {
+        knownByName.set(parsed[1], { key, files: new Set(parsed[2].split(', ').filter(Boolean)) });
+    }
+}
+
 function collectFiles(dir, extension) {
     const files = [];
     for (const entry of readdirSync(join(ROOT, dir), { withFileTypes: true })) {
@@ -54,15 +80,121 @@ function collectFiles(dir, extension) {
     return files;
 }
 
+/**
+ * Имя пакета и путь внутри него. Относительный и абсолютный спецификаторы пакетом не бывают;
+ * приставки `pkg:` и `~` снимаются — ими зовут тот же пакет разные сборщики.
+ */
+function packageOf(specifier) {
+    const clean = specifier.replace(/^pkg:/, '').replace(/^~/, '');
+    if (clean === '' || clean.startsWith('.') || clean.startsWith('/')) {
+        return null;
+    }
+    const parts = clean.split('/');
+    const name = clean.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+    if (clean.startsWith('@') && parts.length < 2) {
+        return null;
+    }
+
+    return { name, rest: clean.slice(name.length).replace(/^\//, '') };
+}
+
+/**
+ * Файл пакета, названный подключением. Каталог ищется разрешением модуля от того места, где
+ * подключение написано: пакет подпроекта в корне дерева не лежит вовсе, а менеджер вправе
+ * держать рядом несколько версий сразу. Не нашлось — `null`: дерево без этого пакета получает
+ * сверку своих объявлений, а не отказ чтения.
+ */
+function fileOfPackage(from, { name, rest }) {
+    let manifest;
+    try {
+        manifest = createRequire(join(ROOT, from, 'package.json')).resolve(`${name}/package.json`);
+    } catch {
+        return null;
+    }
+
+    const base = dirname(manifest);
+    const tail = rest === '' ? 'index' : rest;
+    const candidates = [
+        join(base, tail),
+        join(base, `${tail}.scss`),
+        join(base, dirname(tail), `_${basename(tail)}.scss`),
+        join(base, tail, '_index.scss'),
+        join(base, tail, 'index.scss'),
+    ];
+
+    return candidates.find((path) => existsSync(path) && statSync(path).isFile()) ?? null;
+}
+
+/**
+ * Имена элементов, объявленных файлом стилей. Имя собирается из вложенности: `&__head { &-icon }`
+ * объявляет `head-icon`, и колен у него бывает сколько угодно. Читая только то, что стоит после
+ * `__` целиком, проверка числила долгом исправную вёрстку — правило работает, класс красит, а
+ * снять его значило бы сломать экран.
+ *
+ * Хвост без головы именем не становится: `&-<хвост>`, стоящий вне блока элемента, принадлежит
+ * чужому селектору, и приписать его было бы выдумыванием объявления.
+ */
+function elementNames(text) {
+    const names = new Set();
+    const stack = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        const parent = stack.length ? stack[stack.length - 1] : '';
+        const head = HEAD_RE.exec(line);
+        const tail = TAIL_RE.exec(line);
+        let current = parent;
+
+        if (head) {
+            current = head[1];
+        } else if (tail && parent) {
+            current = `${parent}-${tail[1]}`;
+            names.add(current);
+        }
+
+        for (const match of line.matchAll(RULE_RE)) {
+            names.add(match[1]);
+        }
+
+        for (let index = 0; index < (line.match(/{/g) ?? []).length; index += 1) {
+            stack.push(current);
+        }
+        for (let index = 0; index < (line.match(/}/g) ?? []).length && stack.length; index += 1) {
+            stack.pop();
+        }
+    }
+
+    return names;
+}
+
+/**
+ * Объявления из пакетов, подключённых самим приложением. Читается ровно названный файл:
+ * подключения внутри него не разбираются — объявленным считается то, что приложение назвало.
+ */
+function declarationsFromPackages(styleFiles) {
+    const names = new Set();
+    for (const path of styleFiles) {
+        for (const [, specifier] of readFileSync(join(ROOT, path), 'utf8').matchAll(USE_RE)) {
+            const parsed = packageOf(specifier);
+            const file = parsed && fileOfPackage(dirname(path), parsed);
+            if (!file) {
+                continue;
+            }
+            elementNames(readFileSync(file, 'utf8')).forEach((name) => names.add(name));
+        }
+    }
+
+    return names;
+}
+
 const declared = new Set();
 const usedIn = new Map();
 
 for (const root of SOURCE_ROOTS) {
-    for (const path of collectFiles(root, '.scss')) {
-        for (const match of readFileSync(join(ROOT, path), 'utf8').matchAll(RULE_RE)) {
-            declared.add(match[1]);
-        }
+    const styleFiles = collectFiles(root, '.scss');
+    for (const path of styleFiles) {
+        elementNames(readFileSync(join(ROOT, path), 'utf8')).forEach((name) => declared.add(name));
     }
+    declarationsFromPackages(styleFiles).forEach((name) => declared.add(name));
 
     for (const path of collectFiles(root, '.html')) {
         for (const match of readFileSync(join(ROOT, path), 'utf8').matchAll(ELEM_RE)) {
@@ -82,21 +214,58 @@ for (const [name, files] of [...usedIn].sort(([first], [second]) => first.locale
         continue;
     }
     const where = [...files].sort().join(', ');
-    findings.push({ key: `elem ${name} @ ${where}`, text: `rtElem="${name}" — правила нет ни в одном файле стилей: ${where}` });
+    findings.push({
+        name,
+        files: new Set(files),
+        key: `elem ${name} @ ${where}`,
+        text: `rtElem="${name}" — правила нет ни в одном файле стилей: ${where}`,
+    });
 }
 
-const fresh = findings.filter((finding) => !known.has(finding.key));
-const staleKeys = [...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.text),
-    ...staleKeys.map((key) => `${key}: значится в ${ALLOWLIST}, но класс уже подкреплён правилом — строку убрать`),
-];
+/**
+ * Чем перечень файлов у находки разошёлся со строкой списка: что добавилось и что ушло. Рост —
+ * расхождение, сокращение — починка; одинаково их читать нельзя, а сверять ключ целиком значило
+ * бы объявлять тот же долг новым.
+ */
+function changedFiles(finding, line) {
+    return {
+        added: [...finding.files].filter((path) => !line.files.has(path)).sort(),
+        gone: [...line.files].filter((path) => !finding.files.has(path)).sort(),
+    };
+}
+
+const problems = [];
+const notes = [];
+const matchedKeys = new Set();
+
+for (const finding of findings) {
+    const line = knownByName.get(finding.name);
+    if (!line) {
+        problems.push(finding.text);
+        continue;
+    }
+    matchedKeys.add(line.key);
+
+    const { added, gone } = changedFiles(finding, line);
+    if (added.length > 0) {
+        problems.push(`elem ${finding.name}: долг разросся — класс появился ещё в ${added.join(', ')}; снять его оттуда`);
+    } else if (gone.length > 0) {
+        notes.push(
+            `elem ${finding.name}: долг сократился — класса больше нет в ${gone.join(', ')}; перечень в строке списка можно поправить`
+        );
+    }
+}
+
+for (const key of known) {
+    if (!matchedKeys.has(key)) {
+        problems.push(`${key}: значится в ${ALLOWLIST}, но класс уже подкреплён правилом — строку убрать`);
+    }
+}
 
 if (problems.length > 0) {
     console.error(`check-styles: расхождений ${problems.length}\n`);
@@ -104,6 +273,7 @@ if (problems.length > 0) {
     process.exit(1);
 }
 
+notes.forEach((note) => console.log(`  ${note}`));
 console.log(
     `check-styles: классов без правила ${findings.length}, из них принято ${findings.length - debt.size}, долг ${debt.size} — новых нет`
 );

package/assets/checks/lib-boundaries.mjs

@@ -0,0 +1,143 @@
+/**
+ * Границы и теги: где либа описана как источник, чей список зависимостей обязан оставаться
+ * пустым и что видно основанию семейства. Все три предмета читают одни и те же файлы
+ * `eslint/boundaries/domains/`, и врозь их не разложить.
+ *
+ * Имя не начинается с `check-`: перебором таких имён умолчание пакета собирает набор гейта
+ * пуша, и помощник с ним гейт стал бы гонять как отдельную проверку.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { BOUNDARIES_DIR, FAMILIES, isDir, projectTag, report } from './lib-common.mjs';
+import { CONFIG, ROOT } from './rt-kit-checks.config.mjs';
+
+/**
+ * Либа должна быть описана ровно одним `sourceTag` и ровно в одном файле границ:
+ * описанная дважды либа означает два разных allowlist'а на неё, и какой победит —
+ * вопрос порядка сборки. В чужих allowlist'ах тег, наоборот, встречается сколько
+ * угодно раз: это перечисление тех, кому либа видна.
+ */
+function checkBoundaries(libs) {
+    if (!isDir(BOUNDARIES_DIR)) {
+        report(BOUNDARIES_DIR, 'каталога с файлами границ нет');
+
+        return;
+    }
+
+    const files = readdirSync(join(ROOT, BOUNDARIES_DIR)).filter((name) => name.endsWith('.config.mjs'));
+    const sources = files.map((name) => ({ name, text: readFileSync(join(ROOT, BOUNDARIES_DIR, name), 'utf8') }));
+
+    for (const libPath of libs) {
+        const tag = projectTag(libPath);
+        const declaration = `sourceTag: '${tag}'`;
+        const owners = sources.flatMap(({ name, text }) => {
+            const count = text.split(declaration).length - 1;
+
+            return count > 0 ? Array.from({ length: count }, () => name) : [];
+        });
+
+        if (owners.length === 0) {
+            report(libPath, `тег ${tag} не описан ни в одном файле ${BOUNDARIES_DIR}/`);
+        } else if (owners.length > 1) {
+            report(libPath, `тег ${tag} описан ${owners.length} раза: ${owners.join(', ')}`);
+        }
+    }
+}
+
+/**
+ * Либы, у которых список зависимостей обязан оставаться пустым. Барель такой либы
+ * уезжает в бандл бэкенда, а сборка API идёт без tree-shaking: любая зависимость
+ * расходится оттуда по всему графу.
+ *
+ * Теги называет дерево: имя тега — его собственное слово, и зашитое здесь требовало бы описания
+ * границ под либу, которой в дереве нет вовсе. Пусто — таких либ дерево не держит.
+ */
+const NO_DEPENDENCY_TAGS = CONFIG.noDependencyTags;
+
+function checkNoDependencyLibs() {
+    if (!isDir(BOUNDARIES_DIR)) {
+        return;
+    }
+
+    const files = readdirSync(join(ROOT, BOUNDARIES_DIR)).filter((name) => name.endsWith('.config.mjs'));
+
+    for (const tag of NO_DEPENDENCY_TAGS) {
+        const declaration = `sourceTag: '${tag}'`;
+        let described = false;
+
+        for (const name of files) {
+            const text = readFileSync(join(ROOT, BOUNDARIES_DIR, name), 'utf8');
+            const declaredAt = text.indexOf(declaration);
+            if (declaredAt === -1) {
+                continue;
+            }
+            described = true;
+
+            const rest = text.slice(declaredAt);
+            const listAt = rest.indexOf('onlyDependOnLibsWithTags:');
+            const opensAt = rest.indexOf('[', listAt);
+            const closesAt = rest.indexOf(']', opensAt);
+            if (listAt === -1 || opensAt === -1 || closesAt === -1) {
+                report(`${BOUNDARIES_DIR}/${name}`, `у ${tag} не найден список зависимостей`);
+                continue;
+            }
+
+            const dependencies = rest.slice(opensAt + 1, closesAt).trim();
+            if (dependencies.length > 0) {
+                report(`${BOUNDARIES_DIR}/${name}`, `${tag} ни от кого не зависит, а его список непуст: ${dependencies}`);
+            }
+        }
+
+        if (!described) {
+            report(BOUNDARIES_DIR, `тег ${tag} не описан ни в одном файле границ`);
+        }
+    }
+}
+
+/**
+ * Основание семейства видит `common/util` и слои `util` общих доменов своей
+ * семьи. Всё сверх этого названо строкой здесь: основание зовут все домены, и
+ * любая его зависимость становится общей для всей семьи.
+ */
+const CORE_EXCEPTIONS = {
+    // Транспорт Connect в admin-transport.provider.ts: дескриптор логина и токен транспорта
+    'scope:admin-core': ['scope:common-proto', 'scope:common-connect'],
+};
+
+/** `scope:<семья>-common-<домен>-util` — слой `util` общего домена той же семьи */
+const isFamilyCommonUtil = (tag, family) => new RegExp(`^scope:${family}-common-[a-z0-9-]+-util$`).test(tag);
+
+async function checkCoreLibs() {
+    // Свод границ есть не у всякого дерева с доменной сеткой: он собирается отдельным файлом, и
+    // пока его отсутствие не обрабатывалось, проверка падала на импорте — то есть отвечала
+    // поломкой на дерево, где границы объявлены иначе.
+    const boundaries = join(ROOT, 'eslint/boundaries/index.mjs');
+    if (!existsSync(boundaries)) {
+        console.log('пропущено: свода границ eslint/boundaries/index.mjs в дереве нет');
+
+        return;
+    }
+    const { allBoundaries } = await import(boundaries);
+
+    for (const family of FAMILIES) {
+        const tag = `scope:${family}-core`;
+        const rule = allBoundaries.find((entry) => entry.sourceTag === tag);
+        if (!rule) {
+            continue;
+        }
+
+        const allowed = CORE_EXCEPTIONS[tag] ?? [];
+        for (const dependency of rule.onlyDependOnLibsWithTags ?? []) {
+            if (dependency === 'scope:common-util' || isFamilyCommonUtil(dependency, family) || allowed.includes(dependency)) {
+                continue;
+            }
+            report(
+                `${BOUNDARIES_DIR}/${family}-core.config.mjs`,
+                `${tag} видит ${dependency}: основанию семейства доступны только scope:common-util и scope:${family}-common-*-util`
+            );
+        }
+    }
+}
+
+export { checkBoundaries, checkCoreLibs, checkNoDependencyLibs };

package/assets/checks/lib-common.mjs

@@ -0,0 +1,149 @@
+/**
+ * Общее для всех предметов сверки раскладки либ: состав слоёв каждой формы домена, чтение
+ * дерева, список принятых долгов и то, как из пути либы получаются её имя, тег и алиас.
+ *
+ * Модуль назван не `check-*`, и это не украшение: умолчание пакета собирает набор гейта пуша
+ * перебором имён `check-<что>.mjs` в каталоге проверок, и помощник с таким именем гейт стал бы
+ * гонять как отдельную проверку.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CONFIG, ROOT, readAllowlist } from './rt-kit-checks.config.mjs';
+
+const FAMILIES = CONFIG.families;
+/**
+ * Корень либ и семья бэкенда берутся из настройки дерева, а не из кода: у дерева, которое
+ * держит либы под другим именем, обход шёл мимо кода и проверка зеленела на пустом каталоге —
+ * то есть отвечала «нарушений нет» там, где она не смотрела вовсе.
+ */
+const LIBS_ROOT = CONFIG.libsRoot;
+const API_FAMILY = CONFIG.apiFamily;
+/**
+ * Приставка селекторов, обязательная либам фронта. Слово принадлежит дереву целиком; пусто —
+ * приставка здесь ничего не значит, и проверка о ней молчит.
+ */
+const LIB_PREFIX = CONFIG.libPrefix;
+/**
+ * Имена, под которыми в этом дереве лежит барель. Их несколько: публикуемый пакет зовёт свой
+ * `public-api.ts`, а либа доменной сетки — `index.ts`, и оба живут в одном дереве. Имя, не
+ * названное здесь, барелем не считается, и собственный файл в нём читается реэкспортом.
+ */
+const BARREL_FILES = CONFIG.barrelFiles;
+const FLAT_LAYERS = ['api', 'data-access', 'ui', 'util'];
+const FEATURE_DOMAIN_LAYERS = [...FLAT_LAYERS, 'feature', 'shell'].sort();
+const COMMON_DOMAIN_LAYERS = [...FLAT_LAYERS, 'feature'].sort();
+/** У бэкенда нет `ui` и `shell`: отдавать разметку и роутиться ему нечем */
+const API_DOMAIN_LAYERS = ['api', 'data-access', 'feature', 'util'];
+/** Где ищутся либы, оказавшиеся вне доменной сетки */
+const LIB_ROOTS = [...FAMILIES, API_FAMILY].map((family) => `${LIBS_ROOT}/${family}`);
+const REQUIRED_FILES = ['project.json', 'tsconfig.json', 'vitest.config.mts', 'src/index.ts'];
+const BOUNDARIES_DIR = 'eslint/boundaries/domains';
+
+const problems = [];
+const report = (path, message) => problems.push(`${path}: ${message}`);
+
+const readJson = (path) => JSON.parse(readFileSync(join(ROOT, path), 'utf8'));
+const isDir = (path) => existsSync(join(ROOT, path)) && statSync(join(ROOT, path)).isDirectory();
+const IGNORED_DIRS = ['src', 'node_modules'];
+const dirsIn = (path) =>
+    isDir(path)
+        ? readdirSync(join(ROOT, path), { withFileTypes: true })
+              .filter((entry) => entry.isDirectory() && !IGNORED_DIRS.includes(entry.name))
+              .map((entry) => entry.name)
+              .sort()
+        : [];
+const isLib = (path) => existsSync(join(ROOT, path, 'project.json'));
+
+/**
+ * Список принятых долгов. Читается помощником настроек, а не напрямую: файла в свежем дереве
+ * нет вовсе, и прямое чтение роняло проверку отказом «нет такого файла» — то есть первая же
+ * установка получала поломку вместо отчёта о том, что долгов нет.
+ */
+const allowlist = readAllowlist('lib-layers');
+const pathsOf = (key) => (allowlist[key] ?? []).map((exception) => exception.path);
+
+/** Паттерн `<корень>/x/*` покрывает и сам каталог `<корень>/x`: исключение снимается целиком */
+const matches = (patterns, path) =>
+    patterns.some((pattern) => {
+        if (!pattern.endsWith('/*')) {
+            return path === pattern;
+        }
+        const prefix = pattern.slice(0, -2);
+
+        return path === prefix || path.startsWith(`${prefix}/`);
+    });
+
+/** Каталог, который доменом не является вовсе: основание семейства, общие либы, бэкенд */
+const isNotDomain = (path) => matches(pathsOf('notDomains'), path);
+
+/** Домен старой раскладки: не проверяется ни как домен, ни как набор либ — уезжает целиком */
+const isLegacyDomain = (path) => matches(pathsOf('legacyDomains'), path);
+
+/** Либа старой раскладки внутри живого домена: домен проверяется, сама либа — нет */
+const isLegacyLib = (path) => matches(pathsOf('legacyLibs'), path);
+
+/** Домен, которому один заполненный слой разрешён: причина названа в списке исключений */
+const isSingleLayerDomain = (path) => matches(pathsOf('singleLayerDomains'), path);
+
+/** Пути, которые обход либ обязан пропустить */
+const isIgnoredLib = (path) => isNotDomain(path) || isLegacyDomain(path) || isLegacyLib(path);
+
+const projectName = (libPath) => libPath.replace(/^libs\//, '').replaceAll('/', '-');
+const projectTag = (libPath) => `scope:${projectName(libPath)}`;
+const importAlias = (libPath) => `${CONFIG.importScope}/${libPath.slice(`${LIBS_ROOT}/`.length)}`;
+
+/**
+ * Файлы либы, кроме бареля: барель есть у пустого слоя так же, как у заполненного, и
+ * пустой слой от заполненного по нему не отличить.
+ */
+function sourceCount(libPath) {
+    const inside = (dir) => {
+        let total = 0;
+        for (const entry of readdirSync(join(ROOT, dir), { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.includes(entry.name)) {
+                    total += inside(`${dir}/${entry.name}`);
+                }
+            } else if (entry.name.endsWith('.ts')) {
+                total += 1;
+            }
+        }
+
+        return total;
+    };
+
+    return isDir(`${libPath}/src/lib`) ? inside(`${libPath}/src/lib`) : 0;
+}
+
+export {
+    FAMILIES,
+    LIBS_ROOT,
+    API_FAMILY,
+    LIB_PREFIX,
+    BARREL_FILES,
+    FLAT_LAYERS,
+    FEATURE_DOMAIN_LAYERS,
+    COMMON_DOMAIN_LAYERS,
+    API_DOMAIN_LAYERS,
+    LIB_ROOTS,
+    REQUIRED_FILES,
+    BOUNDARIES_DIR,
+    IGNORED_DIRS,
+    allowlist,
+    problems,
+    report,
+    readJson,
+    isDir,
+    dirsIn,
+    isLib,
+    isNotDomain,
+    isLegacyDomain,
+    isLegacyLib,
+    isSingleLayerDomain,
+    isIgnoredLib,
+    projectName,
+    projectTag,
+    importAlias,
+    sourceCount,
+};