@rt-tools/agent-kit 0.8.3 → 0.9.1

package/assets/checks/lib-domains.mjs

@@ -0,0 +1,205 @@
+/**
+ * Доменная сетка: какие каталоги считаются доменами, из каких слоёв состоит каждая их форма и
+ * какие либы в них лежат. Отсюда же выходят либы, оказавшиеся вне сетки, и плоские либы
+ * бэкенда — обе группы дальше проверяются наравне с доменными.
+ *
+ * Имя не начинается с `check-`: перебором таких имён умолчание пакета собирает набор гейта
+ * пуша, и помощник с ним гейт стал бы гонять как отдельную проверку.
+ */
+import {
+    API_DOMAIN_LAYERS,
+    API_FAMILY,
+    COMMON_DOMAIN_LAYERS,
+    FAMILIES,
+    FEATURE_DOMAIN_LAYERS,
+    FLAT_LAYERS,
+    LIBS_ROOT,
+    LIB_ROOTS,
+    allowlist,
+    dirsIn,
+    isIgnoredLib,
+    isLegacyDomain,
+    isLegacyLib,
+    isLib,
+    isNotDomain,
+    isSingleLayerDomain,
+    report,
+    sourceCount,
+} from './lib-common.mjs';
+
+/**
+ * Домен ли это. Домен заводится под предмет, и предмет виден по тому, что заполнен у
+ * домена не один слой: экраны и состояние, запросы и механика, выход к чужому и то,
+ * что мы отдаём. Заполнен ровно один — это слот, который заполнит следующая задача, и
+ * от домена он не отличим ничем, кроме намерения.
+ *
+ * Домен вносится строкой в список исключений вместе с причиной, и причина бывает
+ * настоящей: сборка PDF со своими шрифтами не едет ни в чей чужой граф зависимостей.
+ */
+function checkDomainIsFilled(domainPath, libs) {
+    if (isSingleLayerDomain(domainPath)) {
+        return;
+    }
+    const filled = libs.filter((libPath) => sourceCount(libPath) > 0);
+    if (libs.length > 1 && filled.length === 1) {
+        report(
+            domainPath,
+            `заполнен один слой — \`${filled[0].slice(domainPath.length + 1)}\`: домен от слота этим не отличить. ` +
+                'Либо содержимое переезжает в существующую либу, либо домен вносится строкой с причиной в `singleLayerDomains`'
+        );
+    }
+}
+
+/** Собирает пути всех либ домена и попутно проверяет состав его слоёв */
+function collectDomainLibs(domainPath, isCommon) {
+    const expected = isCommon ? COMMON_DOMAIN_LAYERS : FEATURE_DOMAIN_LAYERS;
+    const actual = dirsIn(domainPath);
+
+    const missing = expected.filter((layer) => !actual.includes(layer));
+    const extra = actual.filter((layer) => !expected.includes(layer));
+    if (missing.length > 0) {
+        report(domainPath, `нет слоёв: ${missing.join(', ')}`);
+    }
+    if (extra.length > 0) {
+        report(
+            domainPath,
+            `лишние каталоги: ${extra.join(', ')}${extra.includes('shell') && isCommon ? ' (у общего домена shell не бывает: он не роутится)' : ''}`
+        );
+    }
+
+    const libs = actual.filter((layer) => FLAT_LAYERS.includes(layer) || layer === 'shell').map((layer) => `${domainPath}/${layer}`);
+
+    if (actual.includes('feature')) {
+        const featurePath = `${domainPath}/feature`;
+        if (isCommon) {
+            libs.push(featurePath);
+        } else {
+            const screens = dirsIn(featurePath).filter((screen) => isLib(`${featurePath}/${screen}`));
+            if (screens.length === 0) {
+                report(featurePath, 'у фичевого домена `feature` — каталог с либой на экран, здесь ни одной');
+            }
+            libs.push(...screens.map((screen) => `${featurePath}/${screen}`));
+        }
+    }
+
+    checkDomainIsFilled(domainPath, libs);
+
+    return libs;
+}
+
+/**
+ * Домены бэкенда: `<корень либ>/<семья бэкенда>/<домен>` с четырьмя слоями. `feature` бывает и либой,
+ * и каталогом с либой на proto-сервис — по тому же правилу, по которому у
+ * фичевого домена фронта `feature/<экран>`.
+ *
+ * Пустой слой — не дефект: `api` пуст у домена, который ни с кем чужим не
+ * говорит, `data-access` — у того, что не касается базы. Слой всё равно заводится
+ * либой, иначе граница домена объявлена не полностью.
+ */
+function collectApiDomainLibs() {
+    const libs = [];
+
+    for (const entry of dirsIn(`${LIBS_ROOT}/${API_FAMILY}`)) {
+        const domainPath = `${LIBS_ROOT}/${API_FAMILY}/${entry}`;
+        if (isNotDomain(domainPath) || isLegacyDomain(domainPath)) {
+            continue;
+        }
+
+        const actual = dirsIn(domainPath);
+        const missing = API_DOMAIN_LAYERS.filter((layer) => !actual.includes(layer));
+        const extra = actual.filter((layer) => !API_DOMAIN_LAYERS.includes(layer));
+        if (missing.length > 0) {
+            report(domainPath, `нет слоёв: ${missing.join(', ')}`);
+        }
+        if (extra.length > 0) {
+            report(
+                domainPath,
+                `лишние каталоги: ${extra.join(', ')}${extra.includes('shell') || extra.includes('ui') ? ' (у бэкенда ui и shell не бывает)' : ''}`
+            );
+        }
+
+        const domainLibs = actual
+            .filter((layer) => layer !== 'feature' && API_DOMAIN_LAYERS.includes(layer))
+            .map((layer) => `${domainPath}/${layer}`);
+
+        if (actual.includes('feature')) {
+            const featurePath = `${domainPath}/feature`;
+            if (isLib(featurePath)) {
+                domainLibs.push(featurePath);
+            } else {
+                const services = dirsIn(featurePath).filter((service) => isLib(`${featurePath}/${service}`));
+                if (services.length === 0) {
+                    report(featurePath, '`feature` — либа или каталог с либой на proto-сервис, здесь ни того ни другого');
+                }
+                domainLibs.push(...services.map((service) => `${featurePath}/${service}`));
+            }
+        }
+
+        checkDomainIsFilled(domainPath, domainLibs);
+        libs.push(...domainLibs);
+    }
+
+    return libs.sort();
+}
+
+/** Все либы доменной сетки обоих семейств */
+function collectAllDomainLibs() {
+    const libs = [];
+
+    for (const family of FAMILIES) {
+        for (const entry of dirsIn(`${LIBS_ROOT}/${family}`)) {
+            if (entry === 'common') {
+                for (const commonDomain of dirsIn(`${LIBS_ROOT}/${family}/common`)) {
+                    libs.push(...collectDomainLibs(`${LIBS_ROOT}/${family}/common/${commonDomain}`, true));
+                }
+                continue;
+            }
+            const domainPath = `${LIBS_ROOT}/${family}/${entry}`;
+            if (isNotDomain(domainPath) || isLegacyDomain(domainPath)) {
+                continue;
+            }
+            libs.push(...collectDomainLibs(domainPath, false));
+        }
+    }
+
+    return libs.sort();
+}
+
+/** Каждая либа на диске должна быть либой доменной сетки или значиться в allowlist */
+function collectStrayLibs(knownLibs) {
+    const strays = [];
+    const walk = (path) => {
+        if (isLegacyDomain(path) || isNotDomain(path)) {
+            return;
+        }
+        if (isLib(path)) {
+            if (!knownLibs.includes(path) && !isIgnoredLib(path)) {
+                strays.push(path);
+            }
+            // либа старой раскладки может держать внутри себя новые слои — обход продолжается
+            if (!isLegacyLib(path)) {
+                return;
+            }
+        }
+        dirsIn(path).forEach((entry) => walk(`${path}/${entry}`));
+    };
+    LIB_ROOTS.forEach((root) => walk(root));
+
+    return strays;
+}
+
+/**
+ * Плоские либы бэкенда: `<корень либ>/<семья бэкенда>/<домен>`. Лесенки слоёв у них нет по
+ * устройству — домен это одна либа, — но всё остальное проверяется наравне с
+ * доменной сеткой. До сужения исключение по этому корню снимало с них и состав
+ * файлов, и тег, и алиас: новая либа заводилась без `vitest.config.mts`, и
+ * `nx test` по ней молча не гонял ни одной спеки.
+ */
+function collectFlatLibs() {
+    return (allowlist.flatLibRoots ?? [])
+        .flatMap((root) => dirsIn(root).map((entry) => `${root}/${entry}`))
+        .filter((path) => isLib(path))
+        .sort();
+}
+
+export { collectAllDomainLibs, collectApiDomainLibs, collectFlatLibs, collectStrayLibs };

package/assets/checks/lib-manifests.mjs

@@ -0,0 +1,60 @@
+/**
+ * Сама либа: обязательные файлы, имя проекта, приставка селекторов, тег и алиас импорта —
+ * всё, чем `project.json` и `tsconfig.base.json` обязаны совпадать с путём либы на диске.
+ *
+ * Имя не начинается с `check-`: перебором таких имён умолчание пакета собирает набор гейта
+ * пуша, и помощник с ним гейт стал бы гонять как отдельную проверку.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { LIB_PREFIX, REQUIRED_FILES, importAlias, projectName, projectTag, readJson, report } from './lib-common.mjs';
+import { ROOT } from './rt-kit-checks.config.mjs';
+
+function checkLib(libPath, { requirePrefix = true } = {}) {
+    for (const file of REQUIRED_FILES) {
+        if (!existsSync(join(ROOT, libPath, file))) {
+            report(libPath, `нет файла ${file}`);
+        }
+    }
+
+    if (!existsSync(join(ROOT, libPath, 'project.json'))) {
+        return;
+    }
+
+    const project = readJson(`${libPath}/project.json`);
+    if (project.name !== projectName(libPath)) {
+        report(libPath, `имя проекта «${project.name}» не совпадает с путём, ожидается «${projectName(libPath)}»`);
+    }
+    if (project.sourceRoot !== `${libPath}/src`) {
+        report(libPath, `sourceRoot «${project.sourceRoot}» не совпадает с путём`);
+    }
+    // Приставка — про селекторы компонентов, а у бэкенда компонентов нет. Само слово принадлежит
+    // дереву: у каждого оно своё, и зашитое здесь краснело бы на всех либах первого же дерева,
+    // назвавшего свои селекторы иначе. Дерево, не назвавшее приставки, этой проверки не получает.
+    if (requirePrefix && LIB_PREFIX && project.prefix !== LIB_PREFIX) {
+        report(libPath, `prefix «${project.prefix}» вместо обязательного «${LIB_PREFIX}»`);
+    }
+
+    const tags = project.tags ?? [];
+    if (tags.length !== 1) {
+        report(libPath, `тегов ${tags.length}, а должен быть ровно один: ${projectTag(libPath)}`);
+    } else if (tags[0] !== projectTag(libPath)) {
+        report(libPath, `тег «${tags[0]}» не совпадает с путём, ожидается «${projectTag(libPath)}»`);
+    }
+}
+
+function checkAliases(libs) {
+    const paths = readJson('tsconfig.base.json').compilerOptions.paths;
+    for (const libPath of libs) {
+        const alias = importAlias(libPath);
+        const target = `./${libPath}/src/index.ts`;
+        if (!paths[alias]) {
+            report(libPath, `в tsconfig.base.json нет алиаса ${alias}`);
+        } else if (paths[alias][0] !== target) {
+            report(libPath, `алиас ${alias} указывает на ${paths[alias][0]}, а не на ${target}`);
+        }
+    }
+}
+
+export { checkAliases, checkLib };

package/assets/checks/lib-reexports.mjs

@@ -0,0 +1,101 @@
+/**
+ * Барели и реэкспорты: что либа отдаёт наружу и чем это отличается от собственного объявления.
+ *
+ * Имя не начинается с `check-`: перебором таких имён умолчание пакета собирает набор гейта
+ * пуша, и помощник с ним гейт стал бы гонять как отдельную проверку.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { BARREL_FILES, IGNORED_DIRS, isDir, report } from './lib-common.mjs';
+import { CONFIG, ROOT } from './rt-kit-checks.config.mjs';
+
+/** Барель собирает наружу собственные файлы либы, и только они в нём законны */
+const isBarrel = (path) => BARREL_FILES.some((name) => path.endsWith(`/${name}`));
+
+/** Файл той же либы адресуется относительным путём, чужая либа — алиасом */
+const isOwnFile = (module) => module.startsWith('.');
+
+/** `export { X } from '…'` и `import { X } …` вместе с `export { X };` */
+const REEXPORT_FROM = /^export\s+(?:type\s+)?\{([^}]*)\}\s*from\s*'([^']+)';/gm;
+const BARE_EXPORT = /^export\s+(?:type\s+)?\{([^}]*)\};/gm;
+const IMPORTED_NAMES = /^import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*'([^']+)';/gm;
+
+const namesIn = (list) =>
+    list
+        .split(',')
+        .map(
+            (part) =>
+                part
+                    .trim()
+                    .replace(/^type\s+/, '')
+                    .split(/\s+as\s+/)[0]
+        )
+        .filter(Boolean);
+
+/** Файлы либ, кроме спек: реэкспорт в спеке бессмыслен, а обходить их дешевле */
+function collectSourceFiles() {
+    const files = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(join(ROOT, dir), { withFileTypes: true })) {
+            if (IGNORED_DIRS.includes(entry.name) && entry.name !== 'src') {
+                continue;
+            }
+            const path = `${dir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                walk(path);
+            } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.spec.ts')) {
+                files.push(path);
+            }
+        }
+    };
+
+    CONFIG.sourceRoots.filter(isDir).forEach(walk);
+
+    return files;
+}
+
+/**
+ * Символ, объявленный в другой либе, наружу не проходит.
+ *
+ * Реэкспорт заводится тогда, когда потребителю не хватает прав на либу-источник,
+ * и протаскивает её через соседа мимо границы тегов: по графу зависимостей
+ * выходит, что слой её не видит. Ни линт, ни сборка реэкспорт от собственного
+ * объявления не отличают.
+ *
+ * В бареле проверяются только чужие либы: собственные файлы он и собирает.
+ * Пока барель пропускался целиком, чужой символ проходил через него молча —
+ * так `common/util` отдавала работу с датами всему бэкенду через слой `util`
+ * домена Postgres.
+ */
+function checkReexports() {
+    for (const file of collectSourceFiles()) {
+        if (file.includes('/gen/') || file.includes('/generated/')) {
+            continue;
+        }
+
+        const ownFilesAllowed = isBarrel(file);
+        const text = readFileSync(join(ROOT, file), 'utf8');
+        for (const [, list, module] of text.matchAll(REEXPORT_FROM)) {
+            if (ownFilesAllowed && isOwnFile(module)) {
+                continue;
+            }
+            report(file, `реэкспорт из \`${module}\`: ${namesIn(list).join(', ')} — потребитель импортирует их у источника`);
+        }
+
+        const imported = new Map();
+        for (const [, list, module] of text.matchAll(IMPORTED_NAMES)) {
+            namesIn(list).forEach((name) => imported.set(name, module));
+        }
+        for (const [, list] of text.matchAll(BARE_EXPORT)) {
+            for (const name of namesIn(list).filter((name) => imported.has(name))) {
+                if (ownFilesAllowed && isOwnFile(imported.get(name))) {
+                    continue;
+                }
+                report(file, `реэкспорт \`${name}\` из \`${imported.get(name)}\` — потребитель импортирует его у источника`);
+            }
+        }
+    }
+}
+
+export { checkReexports };

package/assets/checks/rt-kit-checks.config.mjs

@@ -95,6 +95,23 @@ const DEFAULTS = {
     apiFamily: 'api',
     /** Область алиасов импорта: `@область/<семья>/<домен>/<слой>` в `tsconfig.base.json`. */
     importScope: '@app',
+    /**
+     * Приставка селекторов, обязательная фронтовым либам. Слово принадлежит дереву: названное
+     * умолчанием, оно краснело бы на каждой либе первого же дерева, у которого приставка своя.
+     * Пусто — приставка не судится вовсе.
+     */
+    libPrefix: '',
+    /**
+     * Теги либ, чей список зависимостей обязан оставаться пустым: их барель уезжает в бандл
+     * бэкенда, а сборка идёт без tree-shaking. Имена тегов — слова дерева, поэтому умолчание
+     * пусто: названное здесь требовало бы описания границ под либу, которой в дереве нет.
+     */
+    noDependencyTags: [],
+    /**
+     * Как в этом дереве зовётся барель. Собственный файл в нём законен, вне его — реэкспорт.
+     * Дерево, которое публикует пакеты, называет здесь и их публичный вход.
+     */
+    barrelFiles: ['index.ts'],
     /**
      * Признаки боевого хранилища: порт, адрес, имя домена. Проверки туда не ходят ни читать,
      * ни писать — схема на проде меняется выкаткой. Пусто — признаков нет, и адрес боевым