@rt-tools/agent-kit 0.5.1 → 0.5.3

package/lib/commands.js

@@ -3,14 +3,17 @@
  * а `process.exit` зовёт только точка входа — иначе ни одну из них нельзя было бы проверить
  * спекой, не перехватывая поток вывода.
  */
-import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { collectAssets } from './assets.js';
 import { isChosen, readCatalog } from './catalog.js';
 import { isUnfilled } from './companion.js';
-import { CONFIG_PATH, DEFAULT_LAYOUT, KINDS, OVERRIDES_DIR, readConfig } from './config.js';
+import { CONFIG_PATH, DEFAULT_LAYOUT, KINDS, OVERRIDES_DIR, PROFILE_FILE, readConfig, RT_KIT_DIR, SKILL_KINDS, } from './config.js';
 import { hooksSection, SETTINGS_PATH } from './hooks-map.js';
+import { DEFAULT_DAYS, KEEP_DAYS, OBSERVATIONS_DIR, readObservations, summarize } from './observations.js';
 import { isRefusal } from './plan.js';
+import { leaksIn, markSent, marksOf, PROPOSALS_DIR, readProposals, TO_PACKAGE } from './proposals.js';
+import { FEEDBACK_LABEL } from './submit.js';
 import { pendingOf, planSync, runSync } from './sync.js';
 import { placeholdersOf } from './vars.js';
 import { readAxes, unansweredAxes } from './variants.js';
@@ -61,6 +64,73 @@ const COMPANION_WORD = {
 const NO_CONFIG = `нет \`${CONFIG_PATH}\` — начни с \`agent-kit init\``;
 /** Куда уезжает прежнее содержимое файла, отданного пакету. */
 export const KEPT_SUFFIX = '.before-rt-kit';
+/**
+ * Имя функции профиля, которую хук ждёт. Обе формы: голая проверка наличия и спрос через
+ * помощника, который о нехватке говорит вслух. Считать одну значило бы недосчитаться ровно тех
+ * хуков, которые перешли на второе.
+ */
+const PROFILE_CALL = /(?:command -v|rt_needs)[ \t]+(rt_[a-z_]+)/g;
+/** Сам помощник функцией профиля не является: его везёт пакет, а не дерево. */
+const PROFILE_HELPER = 'rt_needs';
+/**
+ * Объявление функции: `rt_is_app_code() {`. Не с начала строки — хук объявляет запасной вариант
+ * прямо в условии, и не считать его объявлением значило бы звать недостающим то, что у хука
+ * есть.
+ */
+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;
+        }
+        for (const found of asset.text.matchAll(PROFILE_CALL)) {
+            if (found[1] !== PROFILE_HELPER) {
+                wanted.add(found[1]);
+            }
+        }
+        // Часть общих функций живёт не в профиле, а в соседнем хуке: запись наблюдения объявлена
+        // в хуке наблюдений, и гарды зовут её через ту же проверку наличия. Не считать их
+        // определёнными значило бы требовать от дерева переписать в профиль чужой код.
+        for (const found of asset.text.matchAll(PROFILE_DEFINE)) {
+            defined.add(found[1]);
+        }
+    }
+    if (!wanted.size) {
+        return [];
+    }
+    // Профиль собирается из тех же файлов, что читает сам хук: сперва разложенное умолчание
+    // пакета, поверх — надстройка дерева. Судить по одной надстройке значило бы объявить мёртвым
+    // каждый гард дерева, которое умолчаний не переписывало.
+    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 found of readFileSync(path, 'utf8').matchAll(PROFILE_DEFINE)) {
+            defined.add(found[1]);
+        }
+    }
+    const absent = [...wanted].filter((name) => !defined.has(name)).sort();
+    return [
+        `функции профиля, которых ждут взятые хуки: ${wanted.size}`,
+        ...(absent.length
+            ? [
+                ...absent.map((name) => `  нет функции ${name} — её определяют в ${join(RT_KIT_DIR, PROFILE_FILE)}`),
+                '  хук без своей функции проверку не делает и действие пропускает',
+            ]
+            : ['  все определены']),
+    ];
+}
 const holes = (result) => [...result.missing].map(([asset, names]) => `  ${asset}: нет значений для ${names.map((name) => `{{${name}}}`).join(', ')}`);
 const unfilled = (result) => result.companions.filter(isUnfilled);
 /** Ось без ответа: чем её спрашивают и из чего выбирают. */
@@ -105,10 +175,25 @@ const unboundLines = (result) => result.unbound.length
             .map((line) => `  ${line}`),
     ]
     : [];
+/**
+ * Разорванные связи между ресурсами.
+ *
+ * Печатается предупреждением и кода возврата не меняет: дерево вправе закрыть требование своим
+ * средством. Но и молчать нельзя — дерево, выбравшее паттерн без хука, которым тот живёт,
+ * выглядит исправным, а расходится с пакетом на целую волну работ.
+ */
+const brokenLines = (result) => result.broken.length
+    ? [
+        `требования ресурсов, оставшиеся без ответа: ${result.broken.length}`,
+        ...result.broken.map((link) => `  ${link.id} — требует ${link.requires}: ${link.unknown ? 'нет в пакете' : NOT_CHOSEN}`),
+        '  это предупреждение, а не отказ: требование закрывается своим средством дерева либо выбором ресурса',
+    ]
+    : [];
 const describe = (result) => [
     ...holes(result),
     ...gapLines(result),
     ...unboundLines(result),
+    ...brokenLines(result),
     ...pendingOf(result).map((entry) => `  ${entry.path} — ${STATE_WORD[entry.outcome]}`),
     ...unfilled(result).map((entry) => `  ${entry.path} — ${COMPANION_WORD[entry.state]}`),
     ...abandonedLines(result),
@@ -200,9 +285,12 @@ export function sync(env, check) {
         const empty = unfilled(result);
         // Гард, которого не зовёт настройка агента, — такое же расхождение, как отставший файл:
         // он разложен, он коммитится, и по дереву его не отличить от работающего.
+        // Разорванная связь в счёт расхождений не идёт: дерево вправе закрыть требование своим
+        // средством, и отказ отбивал бы законную раскладку. Но и сходство её не отменяет —
+        // предупреждение печатается и там, где расходиться больше нечему.
         const count = result.missing.size + result.gaps.length + pending.length + empty.length + result.unbound.length;
         if (!count) {
-            return { code: 0, lines: [`sync --check: разложенное сходится с пакетом v${version}`] };
+            return { code: 0, lines: [`sync --check: разложенное сходится с пакетом v${version}`, ...brokenLines(result)] };
         }
         return { code: 1, lines: [`sync --check: расхождений ${count}`, ...describe(result)] };
     }
@@ -298,6 +386,222 @@ export function adopt(env, names) {
         ],
     };
 }
+/**
+ * Сколько незагруженных правил называется поимённо. На коротком отрезке их бывает больше
+ * тридцати, и список во весь экран прячет всё остальное, ради чего сводку и открыли.
+ */
+const UNUSED_SHOWN = 12;
+/** Столбиком: имя и счёт. Ширина по самому длинному имени — иначе счёт читается по одному. */
+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}`);
+};
+/** Имена скилов, разложенных в это дерево: правила, паттерны и скилы без закона. */
+const skillsOf = (config, assetsDir) => collectAssets(config, assetsDir)
+    .filter((asset) => SKILL_KINDS.includes(asset.kind))
+    .map((asset) => asset.name);
+/**
+ * Сводка наблюдений за отрезок дней.
+ *
+ * Отдельная строка про незагруженное — то, ради чего сводка вообще нужна: чем пользуются, видно
+ * и по работе, а вот правило, которое не открыли ни разу, ничем себя не выдаёт. Сокращать текст
+ * правил так же ценно, как дополнять.
+ */
+export function stats(env, options) {
+    const { root, version, assetsDir } = env;
+    const config = readConfig(root);
+    if (!config) {
+        return { code: 1, lines: [NO_CONFIG] };
+    }
+    // Выключенная запись — не пустая сводка: нули на месте наблюдений читаются как «ничего не
+    // делали», тогда как на самом деле никто и не смотрел.
+    if (!config.observe) {
+        return {
+            code: 0,
+            lines: [
+                'запись наблюдений выключена ключом `observe` в конфиге',
+                `включить — убрать ключ или поставить \`"observe": true\`; пишутся они в ${OBSERVATIONS_DIR}/`,
+            ],
+        };
+    }
+    const days = options.days > 0 ? options.days : DEFAULT_DAYS;
+    const result = readObservations(root, options.today, days);
+    const summary = summarize(result.observations, skillsOf(config, assetsDir), days);
+    if (options.json) {
+        return { code: 0, lines: [JSON.stringify({ ...summary, swept: result.swept })] };
+    }
+    if (result.silent) {
+        return {
+            code: 0,
+            lines: [
+                'наблюдений нет: записи не велось ни разу',
+                `их пишут гарды в ${OBSERVATIONS_DIR}/ — проверь, что гарды разложены и подключены в ${SETTINGS_PATH}`,
+            ],
+        };
+    }
+    if (!summary.total) {
+        return {
+            code: 0,
+            lines: [
+                `наблюдений за ${days} дн. нет ни одного, а записи велись раньше`,
+                ...(result.swept.length ? [`снято по сроку хранения (${KEEP_DAYS} дн.): ${result.swept.length}`] : []),
+                'возьми отрезок длиннее: `--days 14`',
+            ],
+        };
+    }
+    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} из ${skillsOf(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}`,
+        ],
+    };
+}
+/** Тело записи: место, повод, готовый текст — и сводка под ними. */
+const issueBody = (proposal, summary, version) => [
+    `Ресурс: \`${proposal.resource}\``,
+    `Пакет: v${version}`,
+    '',
+    proposal.body,
+    '',
+    '## Наблюдения дерева, из которого пришло предложение',
+    '',
+    '```',
+    ...summary,
+    '```',
+    '',
+    'Заведено `agent-kit propose`. Дерево, из которого оно пришло, здесь не называется намеренно.',
+].join('\n');
+/**
+ * Отправка предложений, адресованных пакету.
+ *
+ * Наружу уезжает только адрес «пакет»: «компаньон» и «дерево» — про имена и надстройки этого
+ * дерева, и в репозитории пакета им делать нечего. Перед отправкой текст сверяется на адрес
+ * дерева: файл уезжает в чужой репозиторий целиком, и проверка здесь дешевле, чем разбор потом.
+ */
+export function propose(env, options) {
+    const { root, version } = env;
+    const config = readConfig(root);
+    if (!config) {
+        return { code: 1, lines: [NO_CONFIG] };
+    }
+    if (!options.repository) {
+        return { code: 1, lines: ['куда отправлять — неизвестно: в манифесте пакета нет адреса репозитория'] };
+    }
+    const all = readProposals(root);
+    const mine = all.filter((entry) => entry.address === TO_PACKAGE && !entry.sent);
+    if (!mine.length) {
+        const others = all.filter((entry) => entry.address !== TO_PACKAGE).length;
+        const sent = all.filter((entry) => Boolean(entry.sent)).length;
+        return {
+            code: 0,
+            lines: [
+                'отправлять нечего: предложений с адресом «пакет» и без пометки об отправке нет',
+                ...(others ? [`с другими адресами: ${others} — они правятся здесь же, надстройкой и компаньоном`] : []),
+                ...(sent ? [`уже отправлено: ${sent}`] : []),
+                ...(all.length ? [] : [`предложения кладутся в ${PROPOSALS_DIR}/ — форма в шаблоне \`proposal.md\``]),
+            ],
+        };
+    }
+    // Утечка отбивает отправку целиком, а не свой блок: файл разбирает человек, и «уехало два из
+    // трёх» он прочтёт как «всё в порядке».
+    const marks = marksOf(root, options.remote);
+    const leaked = mine.flatMap((proposal) => leaksIn(proposal.body, marks).map((leak) => ({ proposal, leak })));
+    if (leaked.length) {
+        return {
+            code: 1,
+            lines: [
+                `отправка не начата: в тексте предложений назван адрес этого дерева — ${leaked.length}`,
+                ...leaked.map(({ proposal, leak }) => `  ${proposal.file}:${proposal.line + leak.line} — ${leak.why}\n      ${leak.text}`),
+                'предложение уезжает в чужой репозиторий целиком: правь текст, а не обходи проверку',
+            ],
+        };
+    }
+    if (options.dryRun) {
+        return {
+            code: 0,
+            lines: [
+                `уехало бы записей: ${mine.length} → ${options.repository}, метка ${FEEDBACK_LABEL}`,
+                ...mine.map((entry) => `  ${entry.resource} (${entry.file}:${entry.line})`),
+                'сводка наблюдений едет вместе с ними',
+            ],
+        };
+    }
+    const done = [];
+    for (const proposal of mine) {
+        let url = '';
+        try {
+            url = options.submit({
+                repository: options.repository,
+                title: `предложение: ${proposal.resource}`,
+                body: issueBody(proposal, options.summary, version),
+                label: FEEDBACK_LABEL,
+            });
+        }
+        catch (error) {
+            return {
+                code: 1,
+                lines: [
+                    ...(done.length ? [`отправлено до отказа: ${done.length}`, ...done] : []),
+                    `отправка оборвалась на ${proposal.resource}: ${error.message.split('\n')[0]}`,
+                    // Три причины покрывают почти все отказы, и ни одну из них не видно из
+                    // сообщения помощника: он говорит про метку, доступ и сам себя одинаково глухо.
+                    `проверь: помощник хостинга стоит и вошёл в учётную запись; в ${options.repository} заведена метка ${FEEDBACK_LABEL}; у учётной записи есть право заводить записи`,
+                    'файл предложений остался на месте — отправленное помечено, остальное уедет повторным запуском',
+                ],
+            };
+        }
+        // Пометка ложится сразу, а не после всех: оборвавшаяся отправка иначе увозит половину
+        // предложений и не оставляет следа, по которому видно, какую именно.
+        const path = join(root, proposal.file);
+        writeFileSync(path, markSent(readFileSync(path, 'utf8'), proposal, url), 'utf8');
+        done.push(`  ${proposal.resource} → ${url}`);
+    }
+    return {
+        code: 0,
+        lines: [
+            `заведено записей: ${done.length} в ${options.repository}`,
+            ...done,
+            'разбирается сведением: `/agent-kit-digest` в репозитории пакета — оно и заводит задачу',
+        ],
+    };
+}
 export function doctor(env) {
     const { root, version, assetsDir } = env;
     const config = readConfig(root);
@@ -320,9 +624,16 @@ export function doctor(env) {
     // Ресурс, названный и в отказе, и чужим видом, считается один раз — иначе «не выбрано»
     // уходит в минус, а минус в отчёте читается как поломка счёта, а не как двойной счёт.
     const skipped = config.skip.filter((id) => foreignVariant.every((entry) => entry.id !== id)).length;
+    // Невыбранное называется поимённо: число «не выбрано: 73» не отвечает ни на один вопрос,
+    // ради которого его читают, — ни какого ресурса не хватает, ни требуется ли он соседу.
+    const unchosen = catalog.filter((entry) => !isChosen(entry, config) &&
+        !config.skip.includes(entry.id) &&
+        foreignVariant.every((one) => one.id !== entry.id));
     const lines = [
         `пакет v${version}, везёт ресурсов ${catalog.length}, взято ${taken}`,
         `не выбрано: ${catalog.length - taken - skipped - other}, пропущено: ${skipped}, другой вид: ${other}`,
+        ...unchosen.map((entry) => `  не выбран: ${entry.id}`),
+        ...profileLines(root, assetsDir, config),
         `значений в конфиге: ${Object.keys(config.vars).length}`,
         ...chosen,
         ...[...counted].map(([outcome, count]) => `${STATE_WORD[outcome]}: ${count}`),