@rt-tools/agent-kit 0.8.2 → 0.9.0

package/lib/commands.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- файл делится задачей RT-849 */
 /**
  * Команды и их вывод. Печать отделена от работы: команда возвращает строки и код возврата,
  * а `process.exit` зовёт только точка входа — иначе ни одну из них нельзя было бы проверить
@@ -6,7 +7,8 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { collectAssets } from './assets.js';
-import { cascadeCuts, isChosen, readCatalog } from './catalog.js';
+import { cascadeCuts } from './cascade.js';
+import { isChosen, readCatalog } from './catalog.js';
 import { debtLine, isUnfilled, pathOf as companionPathOf, unaddressedOf } from './companion.js';
 import { CONFIG_PATH, DEFAULT_LAYOUT, KINDS, OVERRIDES_DIR, PROFILE_FILE, readConfig, RT_KIT_DIR } from './config.js';
 import { hooksSection, SETTINGS_PATH } from './hooks-map.js';
@@ -17,6 +19,7 @@ import { pendingOf, planSync, runSync } from './sync.js';
 import { answersRequirement, readTraits, unknownTraits } from './traits.js';
 import { placeholdersOf } from './vars.js';
 import { readAxes, unansweredAxes } from './variants.js';
+import { byText } from './order.js';
 /** Что с файлом сделала раскладка. Прошедшее время здесь правда: `sync` уже записал. */
 const DONE_WORD = {
     create: 'положен',
@@ -58,6 +61,7 @@ const KIND_TITLE = {
     workflows: 'ВОРКФЛОУ',
     templates: 'ШАБЛОНЫ',
     docs: 'ДОКУМЕНТЫ',
+    samples: 'ОБРАЗЦЫ',
 };
 /** Состояние компаньона словами. У заполненного слова нет: о нём говорить нечего. */
 const COMPANION_WORD = {
@@ -82,20 +86,9 @@ const PROFILE_HELPER = 'rt_needs';
  * есть.
  */
 const PROFILE_DEFINE = /(rt_[a-z_]+)\s*\(\)\s*\{/g;
-/**
- * Функции профиля, которых ждут взятые хуки, и те из них, что дерево не определило.
- *
- * Отдельной строкой в разборе состояния потому, что на месте вызова нехватка не видна вовсе:
- * хук выходит с нулём, стоит в настройке, виден в списке — и читается как работающий. Тишина
- * при этом означает разом «нечего проверять», «проверять нечем» и «всё в порядке».
- */
-function profileLines(root, assetsDir, config) {
-    const wanted = new Set();
-    const defined = new Set();
-    for (const asset of collectAssets(config, assetsDir)) {
-        if (asset.kind !== 'hooks') {
-            continue;
-        }
+/** Что взятые хуки зовут у профиля и что определяют сами. */
+function readHooks(assets, wanted, defined) {
+    for (const asset of assets.filter((one) => one.kind === 'hooks')) {
         for (const found of asset.text.matchAll(PROFILE_CALL)) {
             if (found[1] !== PROFILE_HELPER) {
                 wanted.add(found[1]);
@@ -108,23 +101,36 @@ function profileLines(root, assetsDir, config) {
             defined.add(found[1]);
         }
     }
-    if (!wanted.size) {
-        return [];
-    }
+}
+/** Функции, определённые самим профилем: разложенным умолчанием пакета и надстройкой дерева. */
+function readProfiles(root, config, defined) {
     // Профиль собирается из тех же файлов, что читает сам хук: сперва разложенное умолчание
     // пакета, поверх — надстройка дерева. Судить по одной надстройке значило бы объявить мёртвым
     // каждый гард дерева, которое умолчаний не переписывало.
     const defaults = config.layout.defaults ?? DEFAULT_LAYOUT.defaults;
     const sources = [join(root, defaults, PROFILE_FILE), join(root, RT_KIT_DIR, PROFILE_FILE)];
-    for (const path of sources) {
-        if (!existsSync(path)) {
-            continue;
-        }
+    for (const path of sources.filter((one) => existsSync(one))) {
         for (const found of readFileSync(path, 'utf8').matchAll(PROFILE_DEFINE)) {
             defined.add(found[1]);
         }
     }
-    const absent = [...wanted].filter((name) => !defined.has(name)).sort();
+}
+/**
+ * Функции профиля, которых ждут взятые хуки, и те из них, что дерево не определило.
+ *
+ * Отдельной строкой в разборе состояния потому, что на месте вызова нехватка не видна вовсе:
+ * хук выходит с нулём, стоит в настройке, виден в списке — и читается как работающий. Тишина
+ * при этом означает разом «нечего проверять», «проверять нечем» и «всё в порядке».
+ */
+function profileLines(root, assetsDir, config) {
+    const wanted = new Set();
+    const defined = new Set();
+    readHooks([...collectAssets(config, assetsDir)], wanted, defined);
+    if (!wanted.size) {
+        return [];
+    }
+    readProfiles(root, config, defined);
+    const absent = [...wanted].filter((name) => !defined.has(name)).sort(byText);
     return [
         `функции профиля, которых ждут взятые хуки: ${wanted.size}`,
         ...(absent.length
@@ -135,7 +141,14 @@ function profileLines(root, assetsDir, config) {
             : ['  все определены']),
     ];
 }
-const holes = (result) => [...result.missing].map(([asset, names]) => `  ${asset}: нет значений для ${names.map((name) => `{{${name}}}`).join(', ')}`);
+/** Дырка в тексте пакета, как она написана в самом тексте. */
+function holeOf(name) {
+    return `{{${name}}}`;
+}
+const holes = (result) => [...result.missing].map(([asset, names]) => {
+    const written = names.map(holeOf).join(', ');
+    return `  ${asset}: нет значений для ${written}`;
+});
 const unfilled = (result) => result.companions.filter(isUnfilled);
 /**
  * Строка про компаньон, которому нечего сказать.
@@ -200,13 +213,34 @@ function strangeTraits(config, assetsDir) {
 const unboundLines = (result) => result.unbound.length
     ? [
         `гарды разложены, но в \`${SETTINGS_PATH}\` их не зовёт никто: ${result.unbound.length}`,
-        ...result.unbound.map((binding) => `  ${binding.path} — ${binding.event}${binding.matcher ? ` ${binding.matcher}` : ''}`),
+        ...result.unbound.map((binding) => {
+            const matcher = binding.matcher ? ' ' + binding.matcher : '';
+            return `  ${binding.path} — ${binding.event}${matcher}`;
+        }),
         `  вставь в \`${SETTINGS_PATH}\` раздел \`hooks\` — готовый кусок ниже:`,
         ...JSON.stringify({ hooks: hooksSection(result.unbound) }, null, 4)
             .split('\n')
             .map((line) => `  ${line}`),
     ]
     : [];
+/**
+ * Гарды, подписанные не на то, что объявляют.
+ *
+ * Называются обе стороны: объявленное гардом и стоящее в настройке. Одной стороной такую строку
+ * не починить — правится настройка, а верное значение лежит в гарде, и по разнице видно, что
+ * именно до него не доходит.
+ */
+const driftedLines = (result) => result.drifted.length
+    ? [
+        `гарды подписаны не на то, что объявляют: ${result.drifted.length}`,
+        ...result.drifted.flatMap((drift) => [
+            `  ${drift.path} — ${drift.event}`,
+            `    объявлено: ${drift.declared || '(без образца)'}`,
+            `    в настройке: ${drift.bound || '(без образца)'}`,
+        ]),
+        `  поправь образец в \`${SETTINGS_PATH}\` по объявлению гарда: тело его разбирает то, что объявлено`,
+    ]
+    : [];
 /**
  * Разорванные связи между ресурсами.
  *
@@ -230,7 +264,10 @@ const brokenLines = (result) => result.broken.length
 const idleLines = (result) => result.idle.length
     ? [
         `строк отказа, которые ничего не снимают: ${result.idle.length}`,
-        ...result.idle.map((one) => `  ${one.id} — ${one.by ? `снято отказом от ${one.by}` : 'нет в пакете'}`),
+        ...result.idle.map((one) => {
+            const why = one.by ? 'снято отказом от ' + one.by : 'нет в пакете';
+            return `  ${one.id} — ${why}`;
+        }),
         '  это предупреждение, а не отказ: строки убирает дерево, и раскладка идёт дальше',
     ]
     : [];
@@ -293,6 +330,7 @@ const describe = (result) => [
     ...holes(result),
     ...gapLines(result),
     ...unboundLines(result),
+    ...driftedLines(result),
     ...warnings(result),
     ...pendingOf(result).map((entry) => `  ${entry.path} — ${STATE_WORD[entry.outcome]}`),
     ...unfilled(result).map(companionLine),
@@ -310,7 +348,7 @@ function placeholdersIn(config, assetsDir) {
             }
         }
     }
-    return names.sort();
+    return names.sort(byText);
 }
 /**
  * Что проект выбрал при заведении конфига. Пустой список — весь набор; выбор приходит сюда
@@ -322,7 +360,7 @@ export function init(root, only = [], variants = {}, assetsDir = '') {
     if (existsSync(path)) {
         return { code: 0, lines: [`${CONFIG_PATH} уже есть — оставлен как есть`] };
     }
-    const config = { vars: {}, layout: DEFAULT_LAYOUT, variants, only, skip: [] };
+    const config = { vars: {}, layout: DEFAULT_LAYOUT, skip: [], variants, only };
     mkdirSync(join(root, OVERRIDES_DIR), { recursive: true });
     mkdirSync(join(root, CONFIG_PATH, '..'), { recursive: true });
     writeFileSync(path, `${JSON.stringify(config, null, 4)}\n`, 'utf8');
@@ -380,30 +418,34 @@ const staleRefusal = (stale) => ({
         '  собери пакет и повтори',
     ],
 });
-export function sync(env, check) {
-    const { root, version, assetsDir } = env;
-    const config = readConfig(root);
-    if (!config) {
-        return { code: 1, lines: [NO_CONFIG] };
-    }
+/**
+ * Отказ, случившийся до первой записи на диск. Пусто — раскладке ничто не мешает.
+ *
+ * Ось без ответа отбивает раскладку целиком, а не пропускает свои ресурсы молча: правило
+ * поставки бывает в трёх видах, и дерево, не назвавшее свой, осталось бы вовсе без правила
+ * поставки — заметить это можно было бы только по тому, что гейт перестал его требовать.
+ *
+ * Незнакомое свойство — опечатка, и молчать о ней нельзя ни с одной стороны. У дерева она
+ * означает, что помеченного им ресурса оно не получит вовсе; у ресурса — что он не ляжет
+ * никуда и никогда, а причину в имени файла не разглядеть.
+ */
+function refusalBeforeSync(env, config) {
     if (env.stale) {
         return staleRefusal(env.stale);
     }
-    // Ось без ответа отбивает раскладку целиком, а не пропускает свои ресурсы молча: правило
-    // поставки бывает в трёх видах, и дерево, не назвавшее свой, осталось бы вовсе без правила
-    // поставки — заметить это можно было бы только по тому, что гейт перестал его требовать.
-    const unanswered = unansweredAxes(readAxes(assetsDir), config.variants);
+    const unanswered = unansweredAxes(readAxes(env.assetsDir), config.variants);
     if (unanswered.length) {
         return { code: 1, lines: ['раскладка не начата: не выбран вид', ...axisLines(unanswered)] };
     }
-    // Незнакомое свойство — опечатка, и молчать о ней нельзя ни с одной стороны. У дерева она
-    // означает, что помеченного им ресурса оно не получит вовсе; у ресурса — что он не ляжет
-    // никуда и никогда, а причину в имени файла не разглядеть.
-    const strange = strangeTraits(config, assetsDir);
+    const strange = strangeTraits(config, env.assetsDir);
     if (strange.length) {
         return { code: 1, lines: ['раскладка не начата: свойство дерева не объявлено пакетом', ...strange] };
     }
-    if (check) {
+    return null;
+}
+/** Ответ `sync --check`: расхождения считаются, на диск не пишется ничего. */
+function syncCheck(config, root, version, assetsDir) {
+    {
         const result = planSync(config, root, version, assetsDir);
         const pending = pendingOf(result);
         // Незаполненный компаньон — такое же расхождение, как отставший файл: правило разложено,
@@ -414,12 +456,30 @@ export function sync(env, check) {
         // Разорванная связь в счёт расхождений не идёт: дерево вправе закрыть требование своим
         // средством, и отказ отбивал бы законную раскладку. Но и сходство её не отменяет —
         // предупреждение печатается и там, где расходиться больше нечему.
-        const count = result.missing.size + result.gaps.length + pending.length + empty.length + result.unbound.length;
+        //
+        // Гард, подписанный не на то, что объявляет, идёт в счёт по той же причине и с большим
+        // основанием: неподключённый хотя бы не притворяется — этот выглядит работающим, и ветка
+        // его тела, ради которой всё писалось, не исполняется ни разу.
+        const count = result.missing.size + result.gaps.length + pending.length + empty.length + result.unbound.length + result.drifted.length;
         if (!count) {
             return { code: 0, lines: [`sync --check: разложенное сходится с пакетом v${version}`, ...warnings(result)] };
         }
         return { code: 1, lines: [`sync --check: расхождений ${count}`, ...describe(result)] };
     }
+}
+export function sync(env, check) {
+    const { root, version, assetsDir } = env;
+    const config = readConfig(root);
+    if (!config) {
+        return { code: 1, lines: [NO_CONFIG] };
+    }
+    const refusal = refusalBeforeSync(env, config);
+    if (refusal) {
+        return refusal;
+    }
+    if (check) {
+        return syncCheck(config, root, version, assetsDir);
+    }
     const result = runSync(config, root, version, assetsDir);
     // Перечисляются только дырки: раскладка не начата, и назвать файл «положенным» значило бы
     // сказать неправду — на диске его нет.
@@ -456,6 +516,7 @@ export function sync(env, check) {
                 ? [`разложено файлов: ${result.written.length}`, ...result.written.map((path) => `  ${path}`)]
                 : ['всё уже разложено']),
             ...unboundLines(result),
+            ...driftedLines(result),
             ...debtLines(config, root, assetsDir),
             ...warnings(result),
         ],
@@ -524,6 +585,49 @@ const countLines = (counted) => {
     const width = counted.reduce((found, entry) => Math.max(found, entry.name.length), 0);
     return counted.map((entry) => `  ${entry.name.padEnd(width)}  ${entry.count}`);
 };
+/** Сводка строками: загруженное, незагруженное, отбивки гейта и отказы гардов. */
+function statsLines(summary, swept, days, version, laidOut) {
+    return [
+        `наблюдения за ${days} дн., заходов ${summary.sessions}, событий ${summary.total}`,
+        ...(summary.versions.length ? [`версии пакета в записях: ${summary.versions.join(', ')}`] : []),
+        '',
+        `правил загружено: ${summary.loads.reduce((found, entry) => found + entry.count, 0)}`,
+        ...countLines(summary.loads),
+        ...(summary.unused.length
+            ? [
+                '',
+                `разложено и не загружено ни разу: ${summary.unused.length} из ${laidOut}`,
+                ...summary.unused.slice(0, UNUSED_SHOWN).map((name) => `  ${name}`),
+                // Список говорится не весь, и об этом говорится вслух: молчаливый обрыв
+                // читается как «вот они все», и правило, не попавшее в первую дюжину,
+                // считалось бы работающим.
+                ...(summary.unused.length > UNUSED_SHOWN
+                    ? [`  … и ещё ${summary.unused.length - UNUSED_SHOWN} — целиком в \`--json\``]
+                    : []),
+            ]
+            : []),
+        ...(summary.denials.length
+            ? [
+                '',
+                `гейт отбивал: ${summary.denials.reduce((found, entry) => found + entry.count, 0)}`,
+                ...countLines(summary.denials),
+                ...(summary.kinds.length
+                    ? ['  чаще всего на:', ...countLines(summary.kinds).map((line) => `  ${line}`)]
+                    : []),
+            ]
+            : []),
+        ...(summary.guards.length
+            ? [
+                '',
+                `гарды отказывали: ${summary.guards.reduce((found, entry) => found + entry.count, 0)}`,
+                ...countLines(summary.guards),
+            ]
+            : []),
+        ...(swept.length ? ['', `снято по сроку хранения (${KEEP_DAYS} дн.): ${swept.length}`] : []),
+        '',
+        `пакет v${version}`,
+    ];
+}
 /**
  * Сводка наблюдений за отрезок дней.
  *
@@ -575,46 +679,7 @@ export function stats(env, options) {
     }
     return {
         code: 0,
-        lines: [
-            `наблюдения за ${days} дн., заходов ${summary.sessions}, событий ${summary.total}`,
-            ...(summary.versions.length ? [`версии пакета в записях: ${summary.versions.join(', ')}`] : []),
-            '',
-            `правил загружено: ${summary.loads.reduce((found, entry) => found + entry.count, 0)}`,
-            ...countLines(summary.loads),
-            ...(summary.unused.length
-                ? [
-                    '',
-                    `разложено и не загружено ни разу: ${summary.unused.length} из ${laidOutSkills(config, assetsDir).length}`,
-                    ...summary.unused.slice(0, UNUSED_SHOWN).map((name) => `  ${name}`),
-                    // Список говорится не весь, и об этом говорится вслух: молчаливый обрыв
-                    // читается как «вот они все», и правило, не попавшее в первую дюжину,
-                    // считалось бы работающим.
-                    ...(summary.unused.length > UNUSED_SHOWN
-                        ? [`  … и ещё ${summary.unused.length - UNUSED_SHOWN} — целиком в \`--json\``]
-                        : []),
-                ]
-                : []),
-            ...(summary.denials.length
-                ? [
-                    '',
-                    `гейт отбивал: ${summary.denials.reduce((found, entry) => found + entry.count, 0)}`,
-                    ...countLines(summary.denials),
-                    ...(summary.kinds.length
-                        ? ['  чаще всего на:', ...countLines(summary.kinds).map((line) => `  ${line}`)]
-                        : []),
-                ]
-                : []),
-            ...(summary.guards.length
-                ? [
-                    '',
-                    `гарды отказывали: ${summary.guards.reduce((found, entry) => found + entry.count, 0)}`,
-                    ...countLines(summary.guards),
-                ]
-                : []),
-            ...(result.swept.length ? ['', `снято по сроку хранения (${KEEP_DAYS} дн.): ${result.swept.length}`] : []),
-            '',
-            `пакет v${version}`,
-        ],
+        lines: statsLines(summary, result.swept, days, version, laidOutSkills(config, assetsDir).length),
     };
 }
 export function doctor(env) {
@@ -658,7 +723,10 @@ export function doctor(env) {
         `не выбрано: ${catalog.length - taken - skipped - other - cut.size - needsTrait}, пропущено: ${skipped}, другой вид: ${other}, снято каскадом: ${cut.size}, нужно свойство: ${needsTrait}`,
         ...unchosen.map((entry) => `  не выбран: ${entry.id}`),
         ...needing.map((entry) => `  нужно свойство «${entry.needs}»: ${entry.id}`),
-        ...cuts.map((one) => `  снят каскадом: ${one.id} — вслед за ${one.parent}${one.parent === one.root ? '' : `, отвергнут ${one.root}`}`),
+        ...cuts.map((one) => {
+            const root = one.parent === one.root ? '' : ', отвергнут ' + one.root;
+            return `  снят каскадом: ${one.id} — вслед за ${one.parent}${root}`;
+        }),
         ...profileLines(root, assetsDir, config),
         `значений в конфиге: ${Object.keys(config.vars).length}`,
         ...chosen,