agent-quality-kit 0.8.0 → 0.10.0

package/tool/selfcheck/units-repo.mjs

@@ -0,0 +1,164 @@
+// tool/selfcheck/units-repo.mjs — осмотр репозитория: язык по расширению, триггеры записей,
+// выбор рецепта, поиск программы в PATH, совет про браузер у агента.
+//
+// ОТДЕЛЬНЫМ ФАЙЛОМ, а не в units.mjs: тот снова перерос собственный предел в 500 строк, и поймал
+// это наш же file-size-limit. Шов по смыслу: здесь всё, что программа УЗНАЁТ О ЧУЖОМ РЕПОЗИТОРИИ
+// и что из этого следует, — а в units.mjs осталось то, что она делает со своими данными.
+//
+//   node --test tool/selfcheck/units-repo.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { triggerVerdict, recipeFor, EXT_LANG, whichSync, browserServerAdvice, MARKS, isApiSpec } from "../lib/repo.mjs";
+import { CATALOGS, L } from "../i18n/index.mjs";
+import { dirname } from "node:path";
+
+const facts = (over = {}) => ({ langs: new Set(), files: 0, ...over });
+
+// --- опознание языка по расширению -------------------------------------------
+// Найдено на самом aqk: вся программа лежит в .mjs, и запись про отладочную печать
+// пряталась с пояснением «нет языков: javascript» — в проекте, целиком на JavaScript.
+test("расширение .mjs — это JavaScript", () => {
+  assert.equal(EXT_LANG[".mjs"], "javascript");
+  assert.equal(EXT_LANG[".cjs"], "javascript");
+  assert.equal(EXT_LANG[".mts"], "typescript");
+  assert.equal(EXT_LANG[".py"], "python");
+});
+
+
+// --- триггер ------------------------------------------------------------------
+test("без триггера запись не показывается", () => {
+  assert.equal(triggerVerdict({}, facts()).applies, false);
+});
+
+test("условия складываются по И: одно ложное скрывает запись", () => {
+  const rec = { trigger: { langs: "python", files_gt: "10" } };
+  assert.equal(triggerVerdict(rec, facts({ langs: new Set(["python"]), files: 50 })).applies, true);
+  assert.equal(triggerVerdict(rec, facts({ langs: new Set(["python"]), files: 3 })).applies, false);
+  assert.equal(triggerVerdict(rec, facts({ langs: new Set(["go"]), files: 50 })).applies, false);
+});
+
+test("причина, по которой запись скрыта, называется словами", () => {
+  const v = triggerVerdict({ trigger: { langs: "python, typescript" } }, facts({ langs: new Set(["go"]) }));
+  // Сверяем с каталогом, а не с буквами: текст переводится, а выбор причины — нет.
+  assert.equal(v.why, L.trigger.noLangs("python, typescript"));
+});
+
+test("always: false значит «никогда не применимо», а не «условие пропущено»", () => {
+  const v = triggerVerdict({ trigger: { always: "false" } }, facts());
+  assert.equal(v.applies, false);
+});
+
+test("неизвестное условие скрывает запись, а не пропускает её", () => {
+  // Молча пропустить незнакомое условие значит показать запись всем подряд.
+  const v = triggerVerdict({ trigger: { has_kubernetes: "true" } }, facts());
+  assert.equal(v.applies, false);
+  assert.equal(v.why, L.trigger.unknown("has_kubernetes"));
+});
+
+// --- выбор рецепта ------------------------------------------------------------
+test("без родного языка берётся переносимый рецепт, {dir} подставляется", () => {
+  const cmd = recipeFor({ slug: "x", recipes: { any: "bash {gate}/check.sh {dir}" } }, facts());
+  assert.match(cmd, /check\.sh \.$/);
+});
+
+test("рецепта нет — так и сказано, а не пустая строка", () => {
+  assert.equal(recipeFor({ slug: "x", recipes: {} }, facts()), L.recipe.none);
+});
+
+
+// --- поиск программы в PATH ---------------------------------------------------
+// ЗАЧЕМ. Раньше наличие программы проверялось через `command -v` в оболочке. На Windows
+// оболочка — cmd.exe, где такой команды нет, и ответ был «не установлено» ДЛЯ ЛЮБОЙ
+// программы: родной рецепт становился недостижим, гейт молча вставал на слабейший
+// переносимый вариант, а прогон показывал зелёное. Нашлось на чужом прогоне, не у нас.
+test("программа в PATH находится, несуществующая — нет", () => {
+  assert.ok(whichSync("node"), "node обязан находиться: им же запущена эта проверка");
+  assert.equal(whichSync("нет-такой-программы-12345"), null);
+  assert.equal(whichSync(""), null);
+});
+
+test("поиск не зависит от оболочки — работает с пустым окружением", () => {
+  // Тот самый случай: оболочки нет или она другая. Ответ обязан быть «не нашли»,
+  // а не исключение и не ложное «нашли».
+  assert.equal(whichSync("node", { PATH: "" }), null);
+  const dir = dirname(process.execPath);
+  assert.ok(whichSync(process.platform === "win32" ? "node" : "node", { PATH: dir }));
+});
+
+test("команда путём, а не именем, ищется на диске, а не в PATH", () => {
+  assert.ok(whichSync(process.execPath));
+  assert.equal(whichSync("./нет-такого-файла.sh"), null);
+});
+
+
+// --- совет про браузерный MCP-сервер ------------------------------------------
+// Решение владельца 2026-09-08: инструмент, дающий агенту браузер, надо РЕКОМЕНДОВАТЬ.
+// Возражение про нейтральность к вендору здесь не работает: MCP — межвендорный протокол,
+// и сервер одинаково нужен Cursor, Codex и Claude Code.
+//
+// Но совет показывается не всем. Проекту без интерфейса браузер не нужен, а совет, показанный
+// не тому, стоит доверия всем остальным советам — та же норма, что у записей каталога.
+test("совет про браузер даётся проекту с интерфейсом, у которого сервера нет", () => {
+  assert.ok(browserServerAdvice({ has_ui: true }, ""));
+});
+
+test("проекту без интерфейса совет не даётся", () => {
+  assert.equal(browserServerAdvice({ has_ui: false }, ""), null);
+});
+
+// Уже поставил — молчим. Совет, повторяемый тому, кто его выполнил, читается как шум,
+// и следующий совет он пролистает вместе с этим.
+test("сервер уже объявлен — совета нет", () => {
+  const cfg = '{"mcpServers":{"browser":{"command":"npx","args":["-y","chrome-devtools-mcp@1.9.0"]}}}';
+  assert.equal(browserServerAdvice({ has_ui: true }, cfg), null);
+  const pw = '{"mcpServers":{"b":{"command":"npx","args":["@playwright/mcp@0.0.80"]}}}';
+  assert.equal(browserServerAdvice({ has_ui: true }, pw), null);
+});
+
+// Признак «здесь есть договор с чужим кодом»: спецификация API. Считается обходом дерева, а не
+// списком путей, — файл кладут где угодно (`openapi.yaml`, `docs/api/openapi.json`, `schema.yml`
+// рядом с приложением), и фиксированный список промахнулся бы на большинстве проектов.
+//
+// ПОЧЕМУ ПРИЗНАК ОТДЕЛЬНЫЙ, а не часть has_deps. Запись про арбитра контракта не касается
+// библиотеки, консольной программы и монолита без внешнего интерфейса — а таких большинство.
+// Показанной не тому записи не верят, и каталог теряет доверие целиком, а не одной строкой.
+test("спецификация API опознаётся по имени файла, а не по расположению", () => {
+  assert.equal(isApiSpec("openapi.yaml"), true);
+  assert.equal(isApiSpec("openapi.json"), true);
+  assert.equal(isApiSpec("swagger.yml"), true);
+  assert.equal(isApiSpec("asyncapi.yaml"), true);
+  assert.equal(isApiSpec("openapi-v2.yaml"), true);
+  // Имя без расширения спецификации — не она: договор лежит в разбираемом формате.
+  assert.equal(isApiSpec("openapi.md"), false);
+  // Соседи по алфавиту, которые не договор: обычные файлы проекта.
+  assert.equal(isApiSpec("api.yaml"), false);
+  assert.equal(isApiSpec("schema.sql"), false);
+  assert.equal(isApiSpec("package.json"), false);
+});
+
+// Объяснение обязано быть на обоих языках. Признак без объяснения выключает запись НАВСЕГДА и
+// молча — тот же класс, что поймал has_mcp ниже, поэтому сторожится отдельной строкой: в MARKS
+// этого признака нет, он считается обходом, и общая проверка его не увидит.
+test("у признака спецификации API есть объяснение на обоих языках", () => {
+  for (const lang of ["ru", "en"]) {
+    assert.ok(CATALOGS[lang].trigger.flags.has_api_spec, `${lang}: нет объяснения has_api_spec`);
+  }
+});
+
+// Признак репозитория без объяснения — это запись каталога, ВЫКЛЮЧЕННАЯ НАВСЕГДА. Триггер
+// с неизвестным ключом даёт «условие программа не умеет считать», и запись не показывается
+// никому и никогда. Поймано на себе 2026-09-08: завёл has_mcp в списке признаков, объяснение
+// не завёл, и новая запись стала неприменимой в любом репозитории. Видно это было только в
+// выводе doctor на чужой папке — ни один прогон не краснел.
+test("у каждого признака репозитория есть объяснение на обоих языках", () => {
+  const names = MARKS.map(([n]) => n);
+  for (const lang of ["ru", "en"]) {
+    const flags = CATALOGS[lang].trigger.flags;
+    const missing = names.filter((n) => !flags[n]);
+    assert.deepEqual(missing, [], `${lang}: нет объяснения для ${missing.join(", ")}`);
+    // Обратной проверки нет намеренно, и это не лень. Часть признаков считается не по наличию
+    // файла, а обходом содержимого (has_db, has_tests, has_ui), и в этом списке их нет.
+    // Риск несимметричен: объяснение без признака — мёртвая строка, признак без объяснения —
+    // запись каталога, выключенная навсегда и молча. Сторожим ту сторону, которая ломает.
+  }
+});

package/tool/selfcheck/units-vitals.mjs

@@ -0,0 +1,81 @@
+// tool/selfcheck/units-vitals.mjs — «всё ли у самого комплекта подключено».
+//
+// ЗАЧЕМ ЭТА КОМАНДА. `doctor` смотрит на РЕПОЗИТОРИЙ, `prove` — на гейты, `context` — на
+// состояние. На саму обвязку не смотрит никто: стоят ли инструменты, которых требуют
+// объявленные гейты; прописан ли хук в `.git/hooks` на самом деле; получает ли агент состояние.
+// Сегодня это выясняется красным гейтом посреди коммита — в худший момент из возможных.
+//
+//   node --test tool/selfcheck/units-vitals.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { vitalsRows, vitalsVerdict } from "../commands/vitals.mjs";
+
+const ok = { tools: [], unparsed: 0, preCommit: true, sessionHook: true, version: null };
+
+// ТРИ СОСТОЯНИЯ, А НЕ ДВА. «Не подключено» и «не знаем» — разные ответы, и сливать их значит
+// врать ровно тем способом, против которого написан весь комплект.
+test("неизвестное не выдаётся за исправное", () => {
+  const rows = vitalsRows({ ...ok, preCommit: null });
+  const hook = rows.find((r) => r.key === "preCommit");
+  assert.equal(hook.ok, null, "не смогли посмотреть — значит неизвестно, а не «нет»");
+  // И «нет» — тоже отдельное состояние, не равное ни «да», ни «неизвестно».
+  assert.equal(vitalsRows({ ...ok, preCommit: false }).find((r) => r.key === "preCommit").ok, "no");
+});
+
+test("отсутствующий инструмент объявленного гейта — отказ, а не мелочь", () => {
+  const rows = vitalsRows({ ...ok, tools: [{ gate: "lint", prog: "ruff", found: false }] });
+  const t = rows.find((r) => r.key === "tools");
+  assert.equal(t.ok, false);
+  assert.match(t.detail, /ruff/);
+  assert.match(t.detail, /lint/, "названо, КАКОЙ гейт останется без арбитра");
+});
+
+test("все инструменты на месте — строка зелёная", () => {
+  const rows = vitalsRows({ ...ok, tools: [{ gate: "lint", prog: "ruff", found: true }] });
+  assert.equal(rows.find((r) => r.key === "tools").ok, true);
+});
+
+test("непонятые строки манифеста попадают в вердикт", () => {
+  const rows = vitalsRows({ ...ok, unparsed: 2 });
+  assert.equal(rows.find((r) => r.key === "manifest").ok, false);
+});
+
+// Код возврата: красное — отказ, неизвестное — не отказ. Иначе команда краснела бы у всех,
+// у кого просто нет `.claude/`, и её выключили бы в первый день.
+test("вердикт краснеет от отказов, но не от незнания и не от выбора", () => {
+  assert.equal(vitalsVerdict(vitalsRows(ok)), 0);
+  assert.equal(vitalsVerdict(vitalsRows({ ...ok, preCommit: null, sessionHook: null })), 0);
+  // Хука нет — это решение человека (гоняет в конвейере), а не поломка. Команда, которая
+  // кричит «сломано» про выбор, перестаёт читаться вместе с настоящими отказами.
+  assert.equal(vitalsVerdict(vitalsRows({ ...ok, preCommit: false, sessionHook: false })), 0);
+  assert.equal(vitalsVerdict(vitalsRows({ ...ok, unparsed: 1 })), 1);
+  assert.equal(vitalsVerdict(vitalsRows({ ...ok, tools: [{ gate: "g", prog: "x", found: false }] })), 1);
+});
+
+// НАЙДЕНО АУДИТОМ ФИЧ 2026-09-09. Реестр ответил ошибкой (не упал запрос, а вернул не-200) —
+// `latest` остаётся пустым, и строка печатала «0.9.0, свежая». То есть посмотреть не смогли, а
+// сказали «всё хорошо»: ровно тот грех, против которого написан весь комплект, у него самого.
+// Три состояния, а не два: свежая · старая · посмотреть не смогли.
+test("не дозвонились до реестра — так и говорим, а не «свежая»", () => {
+  const unknown = vitalsRows({ ...ok, version: { current: "0.9.0", latest: "" } });
+  const u = unknown.find((r) => r.key === "version");
+  assert.equal(u.ok, null);
+  assert.match(u.detail, /0\.9\.0/);
+  // Утверждение по СМЫСЛУ, а не по слову: «свежая ли, неизвестно» тоже содержит корень «свеж».
+  // Первая версия этого теста ловила именно слово и краснела на честном тексте.
+  assert.match(u.detail, /неизвестн|unknown/i, `незнание не названо: ${u.detail}`);
+
+  const fresh = vitalsRows({ ...ok, version: { current: "0.9.0", latest: "0.9.0" } });
+  const fd = fresh.find((r) => r.key === "version").detail;
+  assert.doesNotMatch(fd, /неизвестн|unknown/i);
+  assert.notEqual(fd, u.detail, "«свежая» и «не знаем» неразличимы по выводу");
+});
+
+// Устаревшая версия — не отказ: человек мог закрепить её сознательно.
+test("старая версия сообщается, но не роняет", () => {
+  const rows = vitalsRows({ ...ok, version: { current: "0.8.0", latest: "0.9.0" } });
+  const v = rows.find((r) => r.key === "version");
+  assert.equal(v.ok, null);
+  assert.match(v.detail, /0\.9\.0/);
+  assert.equal(vitalsVerdict(rows), 0);
+});

package/tool/selfcheck/units.mjs

@@ -12,7 +12,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { parseManifest, manifestWithGate, unknownKeys, entryLifecycle, advisorySet, KNOWN_KEYS } from "../lib/manifest.mjs";
-import { triggerVerdict, recipeFor, stems, overlap, EXT_LANG, whichSync } from "../lib/repo.mjs";
+import { triggerVerdict, recipeFor, stems, overlap, EXT_LANG, whichSync, browserServerAdvice, MARKS } from "../lib/repo.mjs";
 import { scopeOutput, splitAdvice } from "../lib/scope.mjs";
 import { assessBaseline, ITEMS, BASELINE_TOTAL } from "../lib/baseline.mjs";
 import { CATALOGS, pickLang, L } from "../i18n/index.mjs";
@@ -21,16 +21,6 @@ import { dirname } from "node:path";
 
 const facts = (over = {}) => ({ langs: new Set(), files: 0, ...over });
 
-// --- опознание языка по расширению -------------------------------------------
-// Найдено на самом aqk: вся программа лежит в .mjs, и запись про отладочную печать
-// пряталась с пояснением «нет языков: javascript» — в проекте, целиком на JavaScript.
-test("расширение .mjs — это JavaScript", () => {
-  assert.equal(EXT_LANG[".mjs"], "javascript");
-  assert.equal(EXT_LANG[".cjs"], "javascript");
-  assert.equal(EXT_LANG[".mts"], "typescript");
-  assert.equal(EXT_LANG[".py"], "python");
-});
-
 // --- разбор манифеста ---------------------------------------------------------
 test("список читается и строкой в скобках, и пунктами", () => {
   assert.deepEqual(parseManifest("entry: [AGENTS.md, CLAUDE.md]").entry, ["AGENTS.md", "CLAUDE.md"]);
@@ -43,46 +33,6 @@ test("вложенный блок читается словарём, комме
   assert.equal(m.rules, "kit/rules");
 });
 
-// --- триггер ------------------------------------------------------------------
-test("без триггера запись не показывается", () => {
-  assert.equal(triggerVerdict({}, facts()).applies, false);
-});
-
-test("условия складываются по И: одно ложное скрывает запись", () => {
-  const rec = { trigger: { langs: "python", files_gt: "10" } };
-  assert.equal(triggerVerdict(rec, facts({ langs: new Set(["python"]), files: 50 })).applies, true);
-  assert.equal(triggerVerdict(rec, facts({ langs: new Set(["python"]), files: 3 })).applies, false);
-  assert.equal(triggerVerdict(rec, facts({ langs: new Set(["go"]), files: 50 })).applies, false);
-});
-
-test("причина, по которой запись скрыта, называется словами", () => {
-  const v = triggerVerdict({ trigger: { langs: "python, typescript" } }, facts({ langs: new Set(["go"]) }));
-  // Сверяем с каталогом, а не с буквами: текст переводится, а выбор причины — нет.
-  assert.equal(v.why, L.trigger.noLangs("python, typescript"));
-});
-
-test("always: false значит «никогда не применимо», а не «условие пропущено»", () => {
-  const v = triggerVerdict({ trigger: { always: "false" } }, facts());
-  assert.equal(v.applies, false);
-});
-
-test("неизвестное условие скрывает запись, а не пропускает её", () => {
-  // Молча пропустить незнакомое условие значит показать запись всем подряд.
-  const v = triggerVerdict({ trigger: { has_kubernetes: "true" } }, facts());
-  assert.equal(v.applies, false);
-  assert.equal(v.why, L.trigger.unknown("has_kubernetes"));
-});
-
-// --- выбор рецепта ------------------------------------------------------------
-test("без родного языка берётся переносимый рецепт, {dir} подставляется", () => {
-  const cmd = recipeFor({ slug: "x", recipes: { any: "bash {gate}/check.sh {dir}" } }, facts());
-  assert.match(cmd, /check\.sh \.$/);
-});
-
-test("рецепта нет — так и сказано, а не пустая строка", () => {
-  assert.equal(recipeFor({ slug: "x", recipes: {} }, facts()), L.recipe.none);
-});
-
 // --- дедупликация по намерению ------------------------------------------------
 test("разные намерения не путаются служебными словами", () => {
   // Найдено на `aqk new dead-code-not-shipped`: слова not/in/code давали ложное совпадение
@@ -158,30 +108,6 @@ test("язык берётся из AQK_LANG, потом из локали, ин
   assert.equal(pickLang({}), "en");
 });
 
-// --- поиск программы в PATH ---------------------------------------------------
-// ЗАЧЕМ. Раньше наличие программы проверялось через `command -v` в оболочке. На Windows
-// оболочка — cmd.exe, где такой команды нет, и ответ был «не установлено» ДЛЯ ЛЮБОЙ
-// программы: родной рецепт становился недостижим, гейт молча вставал на слабейший
-// переносимый вариант, а прогон показывал зелёное. Нашлось на чужом прогоне, не у нас.
-test("программа в PATH находится, несуществующая — нет", () => {
-  assert.ok(whichSync("node"), "node обязан находиться: им же запущена эта проверка");
-  assert.equal(whichSync("нет-такой-программы-12345"), null);
-  assert.equal(whichSync(""), null);
-});
-
-test("поиск не зависит от оболочки — работает с пустым окружением", () => {
-  // Тот самый случай: оболочки нет или она другая. Ответ обязан быть «не нашли»,
-  // а не исключение и не ложное «нашли».
-  assert.equal(whichSync("node", { PATH: "" }), null);
-  const dir = dirname(process.execPath);
-  assert.ok(whichSync(process.platform === "win32" ? "node" : "node", { PATH: dir }));
-});
-
-test("команда путём, а не именем, ищется на диске, а не в PATH", () => {
-  assert.ok(whichSync(process.execPath));
-  assert.equal(whichSync("./нет-такого-файла.sh"), null);
-});
-
 // --- значок уровня ------------------------------------------------------------
 // ЗАЧЕМ. Значок печатает одна функция, а читает его обратно другое выражение — в том же
 // файле, но независимо. Разойдись они, и `badge --check` перестал бы узнавать собственный
@@ -470,3 +396,5 @@ test("наборы файлов правил совпадают на обоих
   assert.equal(ru.length > 0, true);
 });
 
+
+