agent-quality-kit 0.8.0 → 0.10.0

package/tool/selfcheck/units-banner.mjs

@@ -0,0 +1,65 @@
+// tool/selfcheck/units-banner.mjs — заставка: первая и почти единственная встреча с человеком.
+//
+// ЗАЧЕМ ПРОВЕРЯТЬ КАРТИНКУ. Не ради красоты. Заставка шириной больше окна разъезжается в кашу
+// и портит именно то впечатление, ради которого её и добавили. А в терминале без UTF-8 графика
+// Брайлем превращается в вопросительные знаки — и человек решает, что инструмент сломан.
+//
+//   node --test tool/selfcheck/units-banner.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { banner, BANNER_WIDTH } from "../lib/banner.mjs";
+
+test("заставка влезает в узкое окно", () => {
+  const w = Math.max(...banner().split("\n").map((l) => [...l].length));
+  assert.ok(w <= 40, `ширина ${w}, а бывают окна и в 40 колонок`);
+  assert.equal(w, BANNER_WIDTH, "объявленная ширина обязана совпадать с настоящей");
+});
+
+// Версии в заставке НЕТ намеренно — решение владельца: выпуски частые, и номер в картинке
+// устаревает быстрее всего остального. За версией есть `--version`, она печатается отдельно.
+test("версии в заставке нет", () => {
+  assert.doesNotMatch(banner(), /\d+\.\d+\.\d+/);
+});
+
+// Терминал без UTF-8 превратит Брайль в мусор. Тогда честнее короткая строка, чем каша,
+// по которой человек решит, что инструмент сломан.
+test("без UTF-8 вместо графики короткая строка", () => {
+  const plain = banner({ LANG: "C" });
+  assert.doesNotMatch(plain, /[⣿█]/);
+  assert.match(plain, /aqk/i);
+});
+
+test("отказ от графики уважается переменной", () => {
+  assert.doesNotMatch(banner({ LANG: "ru_RU.UTF-8", AQK_NO_ART: "1" }), /[⣿█]/);
+});
+
+// Кошка центрируется по ВИДИМОЙ части, а не по началу строки: пустой Брайль `⠀` занимает место
+// и ничего не рисует. При равных отступах рисунок выглядел сдвинутым вправо на целый знак —
+// поймано глазом владельца, а не прогоном, и потому закреплено здесь.
+test("кошка стоит по центру надписи", () => {
+  const lines = banner().split("\n");
+  const visible = (l, blanks) => {
+    const a = [...l];
+    let lo = -1, hi = -1;
+    a.forEach((ch, i) => { if (!blanks.has(ch)) { if (lo < 0) lo = i; hi = i; } });
+    return lo < 0 ? null : (lo + hi) / 2;
+  };
+  const catMid = Math.max(...lines.slice(0, 6).map((l) => visible(l, new Set([" ", "⠀"]))));
+  const artMid = Math.max(...lines.slice(7, 13).map((l) => visible(l, new Set([" "]))));
+  assert.ok(Math.abs(catMid - artMid) <= 1, `центры разошлись: кошка ${catMid}, буквы ${artMid}`);
+});
+
+// Подпись центрируется по видимому центру букв, а не по краю строки. Отступ, подобранный на
+// глаз, держится до первой правки рисунка — посчитанный переживёт её.
+test("подпись стоит по центру надписи", () => {
+  const lines = banner().split("\n");
+  const mid = (l, blanks) => {
+    const a = [...l];
+    let lo = -1, hi = -1;
+    a.forEach((ch, i) => { if (!blanks.has(ch)) { if (lo < 0) lo = i; hi = i; } });
+    return lo < 0 ? null : (lo + hi) / 2;
+  };
+  const letters = Math.max(...lines.slice(7, 13).map((l) => mid(l, new Set([" "]))));
+  const tag = mid(lines[lines.length - 1], new Set([" "]));
+  assert.ok(Math.abs(letters - tag) <= 1, `подпись не по центру: буквы ${letters}, подпись ${tag}`);
+});

package/tool/selfcheck/units-brief.mjs

@@ -0,0 +1,97 @@
+// tool/selfcheck/units-brief.mjs — короткая строка присутствия и её ограничитель.
+//
+// ЗАЧЕМ ЭТО ВООБЩЕ. Владелец: «скачал и че дальше, не понятно, работает он вообще или нет».
+// Хук pre-commit молчит на успехе — это его умолчание, проверено по документации: вывод
+// показывается только при провале. То есть комплект, который всё держит, для человека
+// неотличим от невставленного. Это ровно наш собственный порок: тишина неотличима от успеха.
+//
+//   node --test tool/selfcheck/units-brief.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { briefLine, adviceDue, pickAdvice, updateNotice, updateWanted } from "../lib/brief.mjs";
+import { CATALOGS } from "../i18n/index.mjs";
+
+const T = CATALOGS.ru;
+
+// Строка присутствия печатается ВСЕГДА, в том числе когда всё хорошо: именно тогда она и нужна.
+test("строка присутствия несёт числа и уровень", () => {
+  const s = briefLine({ held: 12, todo: 3, level: 2, red: [] }, T);
+  assert.match(s, /12/);
+  assert.match(s, /3/);
+  assert.match(s, /AQK-2/);
+});
+
+// Красное называется первым и поимённо: человек должен видеть, что чинить, не листая вывод.
+test("упавшие гейты названы в самой строке", () => {
+  const s = briefLine({ held: 12, todo: 0, level: 1, red: ["file-size-limit", "duplicate-code"] }, T);
+  assert.match(s, /file-size-limit/);
+  assert.match(s, /duplicate-code/);
+});
+
+// Уровень может быть не вычислен — и тогда так и говорим, а не подставляем ноль.
+test("невычисленный уровень не выдумывается", () => {
+  const s = briefLine({ held: 0, todo: 5, level: -1, red: [] }, T);
+  assert.doesNotMatch(s, /AQK--1|AQK-0/);
+});
+
+// --- ограничитель совета -----------------------------------------------------
+// Совет на КАЖДОМ коммите превращается в шум, а шум пролистывают вместе с настоящими
+// находками. Раз в сутки — это заметно и не мешает.
+test("совет не повторяется чаще раза в сутки", () => {
+  const now = Date.parse("2026-09-08T20:00:00Z");
+  assert.equal(adviceDue(null, now), true, "первый раз показывается");
+  assert.equal(adviceDue("2026-09-08T19:00:00Z", now), false, "час назад — рано");
+  assert.equal(adviceDue("2026-09-07T19:00:00Z", now), true, "сутки прошли");
+});
+
+test("испорченная отметка времени не мешает показать совет", () => {
+  assert.equal(adviceDue("не дата", Date.parse("2026-09-08T20:00:00Z")), true);
+});
+
+// --- выбор совета ------------------------------------------------------------
+// Один совет за раз, а не список: список читается как «у вас всё плохо» и не помогает выбрать.
+test("советуется одна запись, самая первая из непоставленных", () => {
+  const a = pickAdvice([{ slug: "secrets-not-in-code" }, { slug: "file-size-limit" }]);
+  assert.equal(a.slug, "secrets-not-in-code");
+});
+
+test("советовать нечего — совета нет, а не пустая строка", () => {
+  assert.equal(pickAdvice([]), null);
+});
+
+// --- уведомление об обновлении -----------------------------------------------
+// Владелец: «выпускаем часто, никто не будет обновлять — скачают старую версию, а мы там уже
+// ошибки исправили». Верно: у pre-commit версия закреплена в rev:, у GitHub Action в теге,
+// и сами они не двигаются. У `npx` без версии проблемы нет — он всегда берёт свежее.
+//
+// АВТООБНОВЛЕНИЯ НЕТ НАМЕРЕННО. В этот же день выпущена запись, краснеющая на `@latest`:
+// «версия не закреплена, завтра приедет другая». Инструмент, который сам себя подменяет, стоя
+// на воротах коммита, делал бы ровно то, что мы запрещаем другим.
+test("новая версия называется, старая не тревожит", () => {
+  assert.ok(updateNotice("0.8.0", "0.9.0", {}, T));
+  assert.equal(updateNotice("0.9.0", "0.9.0", {}, T), null);
+  assert.equal(updateNotice("0.9.0", "0.8.0", {}, T), null, "откат назад — не обновление");
+});
+
+// Сравнение по числам, а не по строкам: «0.10.0» строкой меньше «0.9.0», и уведомление
+// пропало бы ровно на десятом выпуске — тихо и надолго.
+test("версии сравниваются числами, а не как текст", () => {
+  assert.ok(updateNotice("0.9.0", "0.10.0", {}, T));
+  assert.equal(updateNotice("0.10.0", "0.9.0", {}, T), null);
+  assert.ok(updateNotice("1.2.9", "1.10.0", {}, T));
+});
+
+// Способ обновления зависит от того, как поставлено: у pre-commit это autoupdate, а не npm.
+// Совет «сделай npm i -g» человеку, у которого хук, — это совет мимо, и он его не выполнит.
+test("совет об обновлении соответствует способу установки", () => {
+  assert.match(updateNotice("0.8.0", "0.9.0", { PRE_COMMIT: "1" }, T), /autoupdate/);
+  assert.doesNotMatch(updateNotice("0.8.0", "0.9.0", {}, T), /autoupdate/);
+});
+
+// В конвейере уведомление — шум и лишний запрос: там версия закреплена сознательно, и человека,
+// который бы его прочитал, у экрана нет.
+test("в конвейере и при отказе проверять не спрашиваем вовсе", () => {
+  assert.equal(updateWanted({ CI: "true" }), false);
+  assert.equal(updateWanted({ AQK_UPDATE: "0" }), false);
+  assert.equal(updateWanted({}), true);
+});

package/tool/selfcheck/units-cadence.mjs

@@ -0,0 +1,69 @@
+// Проверки каденции пробы. Написаны ДО кода.
+//
+// ЗАЧЕМ ЭТО ВООБЩЕ. Владелец сформулировал точнее, чем было в замысле: «команду, о которой надо
+// вспомнить, агент не вспомнит, а человек о ней не узнает». Это тот же класс, что файл, который
+// можно не прочитать, — и решать его надо так же: не напоминанием, а тем, что оно случается
+// само. Единица — коммиты, а не сутки: репозиторий, в котором месяц не работали, перепроверять
+// незачем, а сто коммитов за день перепроверить надо.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { probeDue, probeState, probeEvery, PROBE_EVERY } from "../lib/cadence.mjs";
+
+test("порог по умолчанию — сто коммитов, и он назван числом, а не спрятан", () => {
+  assert.equal(PROBE_EVERY, 100);
+});
+
+test("проба нужна, когда с прошлой прошло не меньше порога", () => {
+  assert.equal(probeDue({ at: 100 }, 199, 100), false);
+  assert.equal(probeDue({ at: 100 }, 200, 100), true);
+  assert.equal(probeDue({ at: 100 }, 350, 100), true);
+});
+
+// Пробы не было НИКОГДА — это не «свежая». Молчание здесь означало бы «всё прикрыто»,
+// а прикрыто ли — неизвестно.
+test("если пробы не было вовсе — она нужна", () => {
+  assert.equal(probeDue(null, 1, 100), true);
+  assert.equal(probeDue({}, 500, 100), true);
+});
+
+// История короче порога: проба всё равно нужна один раз, иначе новый репозиторий узнает,
+// чего он не видит, только на сто первом коммите.
+test("в молодом репозитории проба нужна сразу, а не после сотого коммита", () => {
+  assert.equal(probeDue(null, 3, 100), true);
+});
+
+test("счётчик коммитов неизвестен — состояние неизвестно, а не «свежо»", () => {
+  assert.equal(probeDue({ at: 10 }, null, 100), false);
+});
+
+// Состояние для человека и для агента: три исхода, и они не сливаются.
+test("состояние пробы: не делалась, устарела, свежая", () => {
+  assert.deepEqual(probeState(null, 40, 100), { state: "never", behind: null });
+  assert.deepEqual(probeState({ at: 10 }, 40, 100), { state: "fresh", behind: 30 });
+  assert.deepEqual(probeState({ at: 10 }, 210, 100), { state: "stale", behind: 200 });
+  assert.deepEqual(probeState({ at: 10 }, null, 100), { state: "unknown", behind: null });
+});
+
+// Порог — свойство ПРОЕКТА, а не наше: сто коммитов на репозитории с десятком коммитов в час
+// это трижды в день, а на редком проекте столько не наберётся никогда.
+test("порог берётся из манифеста, умолчание остаётся при пустом поле", () => {
+  assert.equal(probeEvery({ probe: "250" }), 250);
+  assert.equal(probeEvery({ probe: 250 }), 250);
+  assert.equal(probeEvery({}), PROBE_EVERY);
+  assert.equal(probeEvery(null), PROBE_EVERY);
+  assert.equal(probeEvery({ probe: "" }), PROBE_EVERY);
+});
+
+// Ноль — это «не делать», а не «делать всегда»: выключатель в манифесте нужен тому, кто не
+// может передать переменную окружения, — например конвейеру чужой площадки.
+test("ноль выключает пробу", () => {
+  assert.equal(probeEvery({ probe: 0 }), 0);
+  assert.equal(probeDue(null, 5, 0), true);
+});
+
+// Неразобранное значение обязано быть НАЗВАНО, а не подменено умолчанием: иначе в манифесте
+// написано одно, а происходит другое — ровно та тихая неправда, против которой весь комплект.
+test("непонятое значение порога — null, а не тихое умолчание", () => {
+  assert.equal(probeEvery({ probe: "часто" }), null);
+  assert.equal(probeEvery({ probe: -5 }), null);
+});

package/tool/selfcheck/units-context.mjs

@@ -163,7 +163,9 @@ test("чужие настройки переживают установку ху
 // не отстал от диспетчера: команда, добавленная в switch и забытая в списке, роняет её.
 test("карта команд не отстаёт от диспетчера", async () => {
   const src = await readFile(new URL("../program.mjs", import.meta.url), "utf8");
-  const dispatched = [...src.matchAll(/^\s{4}case "([a-z-]+)":/gm)].map((m) => m[1]);
+  // Флаговые формы (`--version`, `-v`) в карту не входят: карта перечисляет КОМАНДЫ, а флаг —
+  // второе имя той же команды. Требовать их здесь значило бы дублировать строку справки.
+  const dispatched = [...src.matchAll(/^\s{4}case "([a-z][a-z-]*)":/gm)].map((m) => m[1]);
   assert.ok(dispatched.length >= 10, `в диспетчере найдено ${dispatched.length} команд — разбор сломался`);
   const listed = new Set(commandRows(CATALOGS.ru).map((r) => r.name));
   const missing = dispatched.filter((n) => !listed.has(n));

package/tool/selfcheck/units-level.mjs

@@ -10,7 +10,8 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { commandFor } from "../lib/prove.mjs";
-import { assessLevel, layoutChecks, unknownKeys, KNOWN_KEYS } from "../lib/manifest.mjs";
+import { assessLevel, layoutChecks, unknownKeys, KNOWN_KEYS, parseManifest, coversOf, coversUnproven, unparsedLines } from "../lib/manifest.mjs";
+import { pickLang, langFromText } from "../i18n/index.mjs";
 
 // --- доказательство гейтов ------------------------------------------------------------
 // ЗАЧЕМ. Ступень AQK-2 называлась «гейты доказаны» и проверяла существование двух папок.
@@ -120,3 +121,148 @@ test("docs — известное поле манифеста", () => {
   assert.ok(KNOWN_KEYS.includes("docs"));
   assert.deepEqual(unknownKeys({ docs: ".aqk/docs" }), []);
 });
+
+// --- covers: запись закрыта другим арбитром -----------------------------------
+// Просьба первого чужого пользователя, 2026-09-08, названная им первой: «нельзя сказать, что
+// эта запись у нас закрыта другим гейтом. complexity-limit, no-print-in-prod, swallowed-error
+// держит biome — одним арбитром, точнее переносимого. doctor каждый прогон печатает
+// „применимо, но не поставлено: 5“ — неправду».
+//
+// Неправда в НАШЕМ выводе — самая дорогая из возможных: весь стандарт стоит на том, что вывод
+// не врёт. Поэтому поле есть, но оно не признание на слово: гейт, который «закрывает», обязан
+// быть объявлен в gates:. Иначе covers: становится способом объявить защиту, которой нет, —
+// то самое, против чего написан комплект.
+test("вложенный список в квадратных скобках разбирается как список", () => {
+  const man = parseManifest("covers:\n  lint: [no-print-in-prod, swallowed-error]\n");
+  assert.deepEqual(man.covers.lint, ["no-print-in-prod", "swallowed-error"]);
+});
+
+test("covers отдаёт связь «запись → чем закрыта»", () => {
+  const man = parseManifest("gates:\n  lint: \"biome ci .\"\ncovers:\n  lint: [no-print-in-prod, swallowed-error]\n");
+  const { covered } = coversOf(man);
+  assert.equal(covered.get("no-print-in-prod"), "lint");
+  assert.equal(covered.get("swallowed-error"), "lint");
+});
+
+// Гейт, которого нет в gates:, не закрывает ничего. Промолчать здесь значит выдать
+// несуществующего арбитра за существующего — ровно тот отказ, ради которого всё написано.
+test("закрывать может только объявленный гейт", () => {
+  const man = parseManifest("gates:\n  lint: \"biome ci .\"\ncovers:\n  biome: [complexity-limit]\n");
+  const { covered, unknownGates } = coversOf(man);
+  assert.equal(covered.size, 0, "необъявленный гейт не закрывает ничего");
+  assert.deepEqual(unknownGates, ["biome"]);
+});
+
+test("пустой covers ничего не ломает", () => {
+  const { covered, unknownGates } = coversOf(parseManifest("aqk: 1\n"));
+  assert.equal(covered.size, 0);
+  assert.deepEqual(unknownGates, []);
+});
+
+test("covers — известное поле манифеста", () => {
+  assert.ok(KNOWN_KEYS.includes("covers"));
+  assert.deepEqual(unknownKeys({ covers: {} }), []);
+});
+
+// --- язык вывода: настройка ПРОЕКТА, а не машины ------------------------------
+// Просьба первого чужого пользователя: «язык берётся из LC_ALL/LANG, а на Windows их просто
+// нет: русский проект получает английский вывод. AQK_LANG=ru чинит, но у следующего человека
+// будет своё. Место этому в .aqk.yml». Он прав: язык репозитория — свойство репозитория,
+// а локаль — свойство машины, на которой его сегодня открыли.
+//
+// Порядок намеренный: переменная окружения ВЫШЕ манифеста. Человек, набравший AQK_LANG=en
+// руками, хочет английский именно сейчас — и спорить с ним манифестом значит отнять последнее
+// средство. Манифест выше локали: он про проект, локаль про машину.
+test("манифест задаёт язык, когда переменной окружения нет", () => {
+  assert.equal(pickLang({ LANG: "en_US.UTF-8" }, { lang: "ru" }), "ru");
+});
+
+test("переменная окружения сильнее манифеста", () => {
+  assert.equal(pickLang({ AQK_LANG: "en" }, { lang: "ru" }), "en");
+});
+
+test("без манифеста всё как раньше — локаль, потом английский", () => {
+  assert.equal(pickLang({ LANG: "ru_RU.UTF-8" }, null), "ru");
+  assert.equal(pickLang({}, null), "en");
+});
+
+test("мусор в поле lang не молчит, а просто не действует", () => {
+  assert.equal(pickLang({}, { lang: "клингонский" }), "en");
+});
+
+// Сокращённый разбор языка в i18n/index.mjs существует потому, что каталог строк нужен раньше,
+// чем кто-либо успеет прочитать манифест целиком. Два разбора одного файла — то же, что два
+// свода правил: через месяц они расходятся, и непонятно, какой настоящий. Сверяем ответы.
+test("сокращённый разбор языка не расходится с настоящим", () => {
+  for (const text of [
+    'aqk: 1\nlang: ru\ngates:\n  lint: "true"\n',
+    "aqk: 1\nlang: 'en'\n",
+    'aqk: 1\nlang: "ru"   # комментарий\n',
+    "aqk: 1\ngates:\n  lang: ru\n",     // вложенный ключ — не язык проекта
+    "aqk: 1\n",
+  ]) {
+    assert.equal(langFromText(text), String(parseManifest(text).lang || ""), text);
+  }
+});
+
+// --- заявка covers сверяется, а не принимается на слово -----------------------
+// Поле `covers:` я завёл этим же утром и сам записал в коммит: «снимает запись с долга по
+// СЛОВУ человека; проверить, что чужой гейт ловит то же самое, машина не может». К вечеру
+// выяснилось, что это не теория. Запуск на настоящем `ruff.toml` из живого проекта: девятнадцать
+// групп правил в `extend-select`, и `print()` не ловится — группы `T20` среди них нет.
+// То есть заявка «no-print-in-prod держит наш lint» была бы ЛОЖНОЙ, а запись ушла бы из долга.
+//
+// Проверяется ровно то, что можно: у записи каталога в рецепте стоят коды правил
+// (`ruff check --select T20`). Если ни команда закрывающего гейта, ни конфиг линтера этих кодов
+// не называют — заявка не подтверждена. Это не «ложь», а «не подтверждено»: правило могло
+// прийти из плагина или пресета, и объявлять такое ошибкой значит краснеть на нормальном укладе.
+test("заявка подтверждена, когда коды правил есть в команде гейта", () => {
+  const man = parseManifest('gates:\n  lint: "ruff check --select T20,BLE ."\ncovers:\n  lint: [no-print-in-prod]\n');
+  const catalog = [{ slug: "no-print-in-prod", recipes: { python: "ruff check --select T20 {dir}" } }];
+  assert.deepEqual(coversUnproven(man, catalog, ""), []);
+});
+
+test("заявка не подтверждена, когда кодов нет нигде", () => {
+  const man = parseManifest('gates:\n  lint: "ruff check ."\ncovers:\n  lint: [no-print-in-prod]\n');
+  const catalog = [{ slug: "no-print-in-prod", recipes: { python: "ruff check --select T20 {dir}" } }];
+  assert.deepEqual(coversUnproven(man, catalog, ""), [{ entry: "no-print-in-prod", gate: "lint", codes: ["T20"] }]);
+});
+
+// Правило может стоять не в команде, а в конфиге линтера — это нормальный уклад, и краснеть
+// на нём нельзя. Настоящий пример: extend-select в ruff.toml.
+test("коды правил в конфиге линтера тоже подтверждают заявку", () => {
+  const man = parseManifest('gates:\n  lint: "ruff check ."\ncovers:\n  lint: [no-print-in-prod]\n');
+  const catalog = [{ slug: "no-print-in-prod", recipes: { python: "ruff check --select T20 {dir}" } }];
+  assert.deepEqual(coversUnproven(man, catalog, 'extend-select = ["I", "T20", "B"]'), []);
+});
+
+// У записи без кодов правил в рецепте сверять нечего — молчим, а не выдумываем вердикт.
+test("запись без кодов правил в рецепте не порождает придирки", () => {
+  const man = parseManifest('gates:\n  lint: "true"\ncovers:\n  lint: [duplicate-code]\n');
+  const catalog = [{ slug: "duplicate-code", recipes: { any: "bash {gate}/check.sh {dir}" } }];
+  assert.deepEqual(coversUnproven(man, catalog, ""), []);
+});
+
+// --- строка манифеста, которую разбор не понял, не исчезает молча ---------------
+// Найдено 2026-09-09 случайно: подсаживал падающий гейт с именем «плохой», чтобы посмотреть
+// на строку присутствия, — и прогон вышел с НУЛЁМ. Гейт не упал: его вообще не было. Разбор
+// принимает имена только латиницей, а строку, которая под это не подошла, ВЫБРАСЫВАЛ без слова.
+//
+// Это наш класс в чистом виде: человек объявил проверку, видит её в файле, а она не
+// существует. Хуже опечатки в имени поля — ту мы называем с 2026-09-06, а эту не называли.
+// Чинится не расширением алфавита, а голосом: любая непонятая строка обязана быть названа.
+test("непонятая строка манифеста называется с номером", () => {
+  const bad = unparsedLines('aqk: 1\ngates:\n  ok: "true"\n  плохой: "false"\n');
+  assert.equal(bad.length, 1);
+  assert.equal(bad[0].line, 4);
+  assert.match(bad[0].text, /плохой/);
+});
+
+test("правильный манифест не порождает жалоб", () => {
+  assert.deepEqual(unparsedLines('aqk: 1\nentry:\n  - AGENTS.md\ngates:\n  ok: "true"\n'), []);
+});
+
+// Комментарии и пустые строки — не находка: они и не должны разбираться.
+test("комментарии и пустые строки не считаются потерянными", () => {
+  assert.deepEqual(unparsedLines("# заметка\n\naqk: 1\n   # ещё\n"), []);
+});

package/tool/selfcheck/units-probe.mjs

@@ -0,0 +1,100 @@
+// Проверки разбора истории для `aqk probe`. Написаны ДО кода: без них нельзя отличить
+// «функция работает» от «функция написана».
+import test from "node:test";
+import assert from "node:assert/strict";
+import { isFix, fixHotspots, probeVerdict } from "../lib/history.mjs";
+import { scanningGates, isCode } from "../commands/probe.mjs";
+
+// Признак починки берётся из ТЕМЫ коммита, а не из тела: тема — единственное, что пишут все,
+// и единственное, что видно в `git log --oneline`. Три написания, потому что репозитории
+// бывают на двух языках и с conventional commits.
+test("темой починки считаются fix, исправ и почин — на обоих языках и с областью", () => {
+  assert.equal(isFix("fix: гейт молчал на красном"), true);
+  assert.equal(isFix("fix(prove): windows-пути"), true);
+  assert.equal(isFix("Исправлено: разбор манифеста"), true);
+  assert.equal(isFix("починка отчёта"), true);
+  assert.equal(isFix("FIX: заглавными тоже"), true);
+});
+
+// Слово «fix» внутри обычной темы починкой не делает: иначе «feat: prefix для путей» попадёт
+// в рейтинг, и рейтинг перестанет что-либо значить.
+test("не всякое упоминание fix — починка", () => {
+  assert.equal(isFix("feat: prefix для путей"), false);
+  assert.equal(isFix("docs: как чинить гейт"), false);
+  assert.equal(isFix("refactor: суффиксы"), false);
+  assert.equal(isFix(""), false);
+});
+
+// НАСТОЯЩИЙ формат `git log --format=%s --name-only`, снятый с живого репозитория 2026-09-09:
+// тема, ПУСТАЯ строка, пути, и сразу следующая тема — без пустой строки перед ней.
+// Первая версия этого теста была написана по моему представлению о формате (пустая строка
+// СЛЕДОВАЛА за файлами), код под неё разобрал историю неверно и нашёл ноль починок там, где
+// их сорок пять. Тот же класс, что и дважды сегодня: проверял замысел, а не вывод.
+const LOG = [
+  "fix: разбор манифеста",
+  "",
+  "tool/lib/manifest.mjs",
+  "tool/selfcheck/units.mjs",
+  "feat: новая запись",
+  "",
+  "kit/gates/x/check.sh",
+  "fix(manifest): кавычки",
+  "",
+  "tool/lib/manifest.mjs",
+  "README.md",
+].join("\n");
+
+test("рейтинг считает только файлы из коммитов-починок", () => {
+  const hot = fixHotspots(LOG, { isCode: () => true });
+  assert.deepEqual(hot[0], { path: "tool/lib/manifest.mjs", fixes: 2 });
+  // Файл из коммита-фичи в рейтинг не попадает вовсе.
+  assert.equal(hot.some((h) => h.path === "kit/gates/x/check.sh"), false);
+});
+
+test("рейтинг отсеивает то, что не код: документ чинят иначе, чем программу", () => {
+  const hot = fixHotspots(LOG, { isCode: (p) => p.endsWith(".mjs") });
+  assert.equal(hot.some((h) => h.path === "README.md"), false);
+  assert.equal(hot.length, 2);
+});
+
+test("пустая история — пустой рейтинг, а не падение", () => {
+  assert.deepEqual(fixHotspots("", { isCode: () => true }), []);
+});
+
+// Три состояния, и сливать их нельзя. «Не смогли проверить» — не «прикрыто»: ровно та
+// подмена, против которой написан весь комплект.
+test("вердикт пробы различает поймано, не поймано и нечем проверить", () => {
+  assert.equal(probeVerdict([{ code: 1 }, { code: 0 }]), "caught");
+  assert.equal(probeVerdict([{ code: 0 }, { code: 0 }]), "blind");
+  assert.equal(probeVerdict([{ code: 2 }, { code: 0 }]), "unknown");
+  // Поймавший гейт сильнее непроверенного: класс закрыт, даже если рядом чего-то не хватает.
+  assert.equal(probeVerdict([{ code: 2 }, { code: 1 }]), "caught");
+  assert.equal(probeVerdict([]), "unknown");
+});
+
+// Пробовать можно только те гейты, которым есть куда подставить каталог: рецепт каталога
+// кончается каталогом проверки, команда, написанная руками, — чем угодно. То же правило, по
+// которому `prove` объявляет запись недоказуемой, а не сломанной.
+test("пробуются только гейты, кончающиеся каталогом проверки", () => {
+  const man = { gates: {
+    ok: "bash gates/x/check.sh .",
+    slash: "bash gates/y/check.sh ./",
+    handmade: "eslint . --max-warnings 0",
+    empty: "",
+  } };
+  assert.deepEqual(scanningGates(man).map(([n]) => n), ["ok", "slash"]);
+});
+
+test("манифест без гейтов не роняет разбор", () => {
+  assert.deepEqual(scanningGates(null), []);
+  assert.deepEqual(scanningGates({ gates: [] }), []);
+});
+
+// Образцы каталога исключены по той же причине, по какой их исключает каждая сканирующая
+// проверка: они существуют, чтобы быть неправильными, и «горячими» быть не могут.
+test("горячим считается код, но не документ и не образец каталога", () => {
+  assert.equal(isCode("src/a.py"), true);
+  assert.equal(isCode("tool/lib/core.mjs"), true);
+  assert.equal(isCode("README.md"), false);
+  assert.equal(isCode("gates/secrets-not-in-code/red/a.py"), false);
+});