agent-quality-kit 0.12.0 → 0.14.0

package/tool/selfcheck/units-prompt.mjs

@@ -0,0 +1,106 @@
+// tool/selfcheck/units-prompt.mjs — задание для агента одним текстом (`aqk prompt`).
+//
+// ЗАЧЕМ. Между диагнозом и действием не было моста: `doctor` пишет человеку, `context` — «как
+// дела» агенту, а «почини вот это, это и это» человек пересказывал сам. Идея — из разбора
+// agentlint (research/competitors/agentlint.md, «Задание для агента»): правила поведения
+// сверху, исправления по весу, в конце — как проверить. Их слабость не берём: у них «проверь» —
+// это «балл вырос», у нас — команда, которая краснеет и зеленеет.
+//
+//   node --test tool/selfcheck/units-prompt.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { taskText } from "../commands/prompt.mjs";
+import { CATALOGS } from "../i18n/index.mjs";
+
+const T = CATALOGS.ru.prompt;
+const base = {
+  self: "aqk", manifest: true, run: { when: "2026-09-11 12:00", red: [], stale: false },
+  blind: [], adopt: [], shim: null, start: [],
+};
+const text = (s) => taskText({ ...base, ...s }, T).join("\n");
+const items = (s) => text(s).split("\n").filter((l) => /^\d+\. /.test(l));
+
+test("правила поведения сверху и проверка в конце — всегда, даже когда пунктов нет", () => {
+  const t = text({});
+  assert.ok(t.indexOf(T.rulesTitle) < t.indexOf(T.verifyTitle), "правила идут до проверки");
+  assert.match(t, /aqk doctor --run/, "без команды проверки «готово» ничем не доказано");
+  assert.match(t, new RegExp(T.empty.slice(0, 20)), "пустое задание сказано словами");
+});
+
+test("красный гейт — пункт с командой, которая его запускает одного", () => {
+  const it = items({ run: { when: "x", red: ["lint", "units"], stale: false } });
+  assert.equal(it.length, 2);
+  assert.match(it[0], /aqk doctor --run --only lint/);
+});
+
+// Прогона не было или он старше последнего коммита: список красных — про другой код. Первый
+// пункт — прогнать; пустое задание при этом было бы утверждением «чисто», которого никто не делал.
+test("нет прогона или он устарел — первый пункт «прогони», а не «всё чисто»", () => {
+  const none = text({ run: null });
+  assert.doesNotMatch(none, new RegExp(T.empty.slice(0, 20)), "без прогона задание не пустое");
+  assert.match(items({ run: null })[0], /aqk doctor --run/);
+  const stale = items({ run: { when: "x", red: ["lint"], stale: true } });
+  assert.match(stale[0], /aqk doctor --run/, "устаревший прогон — сначала прогнать заново");
+});
+
+test("порядок по весу: манифест → красное → брак из пробы → свои проверки → свод → начало", () => {
+  const it = items({
+    manifest: false,
+    run: { when: "x", red: ["lint"], stale: false },
+    blind: [{ slug: "swallowed-error", file: "src/a.py", command: "ruff check --select BLE ." }],
+    adopt: [{ name: "test", cmd: "npm test", source: "package.json" }],
+    shim: "missing",
+    start: [{ slug: "secrets-not-in-code", intent: "ключи не в коде", command: "gitleaks dir ." }],
+  });
+  assert.match(it[0], /aqk init/);
+  assert.match(it[1], /lint/);
+  assert.match(it[2], /swallowed-error.*src\/a\.py/);
+  assert.match(it[3], /npm test/);
+  assert.match(it[4], /@AGENTS\.md/);
+  assert.equal(it.length, 5, "больше пяти за раз агент не удержит");
+  assert.match(text({
+    manifest: false, run: { when: "x", red: ["lint"], stale: false },
+    blind: [{ slug: "s", file: "f", command: "" }], adopt: [{ name: "t", cmd: "c", source: "p" }],
+    shim: "missing", start: [{ slug: "x", intent: "y", command: "" }],
+  }), new RegExp(T.more(1).slice(0, 12)), "остаток назван числом, а не выброшен молча");
+});
+
+test("класс из пробы не повторяется в «начните с»; без готовой команды — aqk add", () => {
+  const it = items({
+    blind: [{ slug: "swallowed-error", file: "src/a.py", command: "" }],
+    start: [{ slug: "swallowed-error", intent: "i", command: "" }, { slug: "todo-without-task", intent: "i", command: "" }],
+  });
+  assert.equal(it.length, 2);
+  assert.match(it[0], /aqk add swallowed-error/);
+  assert.match(it[1], /todo-without-task/);
+});
+
+// Гейт стоит, проба его гоняла — и он пропустил. Не «поставь» (стоит), а «здесь он слеп».
+test("гейт стоит, но пропустил брак из пробы — пункт «разберись», сразу после красных", () => {
+  const it = items({
+    run: { when: "x", red: ["lint"], stale: false },
+    missed: [{ slug: "swallowed-error", file: "src/a.py" }],
+    start: [{ slug: "todo-without-task", intent: "i", command: "" }],
+  });
+  assert.match(it[1], /swallowed-error.*src\/a\.py/);
+  assert.doesNotMatch(it[1], /aqk add/, "гейт уже стоит — ставить его второй раз бессмысленно");
+});
+
+test("у каждого пункта — чем доказать, что готово", () => {
+  const it = items({
+    run: { when: "x", red: ["lint"], stale: false },
+    blind: [{ slug: "swallowed-error", file: "src/a.py", command: "" }],
+    missed: [{ slug: "complexity-limit", file: "src/b.py" }],
+    start: [{ slug: "todo-without-task", intent: "i", command: "" }],
+  });
+  for (const line of it) assert.match(line, new RegExp(T.done.slice(0, 6)), `пункт без арбитра: ${line}`);
+});
+
+test("оба языка несут одни и те же ключи задания", () => {
+  const keys = (o) => Object.keys(o).sort().join(",");
+  assert.equal(keys(CATALOGS.ru.prompt), keys(CATALOGS.en.prompt));
+  // Пункты лежат глубже — пропущенный в одном языке пункт упал бы ошибкой только у того, кто
+  // на этом языке работает.
+  assert.equal(keys(CATALOGS.ru.prompt.item), keys(CATALOGS.en.prompt.item));
+  assert.equal(keys(CATALOGS.ru.prompt.item.shim), keys(CATALOGS.en.prompt.item.shim));
+});

package/tool/selfcheck/units-repo.mjs

@@ -8,7 +8,8 @@
 //   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, startWith } from "../lib/repo.mjs";
+import { triggerVerdict, recipeFor, EXT_LANG, whichSync, browserServerAdvice, MARKS, isApiSpec, claudeSeesRules } from "../lib/repo.mjs";
+import { startWith } from "../lib/advice.mjs";
 import { proposeGates } from "../lib/adopt.mjs";
 import { CATALOGS, L } from "../i18n/index.mjs";
 import { dirname } from "node:path";
@@ -284,3 +285,45 @@ test("с чего начать: при равенстве признаков п
   ];
   assert.deepEqual(startWith(list, { langs: new Set() }, 2).map((e) => e.slug), ["a", "b"]);
 });
+
+// Совет под линтер ПРОЕКТА, а не под язык. Отзыв с живого проекта 2026-09-11: «начни с этих
+// трёх» советовал завести eslint проекту на Biome — комплект читал package.json и Makefile, но не
+// biome.json. Команда для Biome — одно правило разово (`--only`), и `--error-on-warnings`
+// обязателен: правило вне рекомендованных Biome ставит на «предупреждение», и без флага команда
+// выходила с нулём, напечатав находку. Проверено на Biome 2.5.12.
+test("совет проекту на Biome: команда Biome, а не eslint", async () => {
+  const { blindAdvice } = await import("../lib/advice.mjs");
+  const entry = {
+    slug: "no-print-in-prod", biome_rules: "suspicious/noConsole",
+    tool: "https://github.com/eslint/eslint",
+    recipes: { javascript: `eslint --no-config-lookup --rule '{"no-console":"error"}' {dir}` },
+  };
+  const biome = blindAdvice(entry, { langs: new Set(["typescript"]), has_biome: true });
+  assert.equal(biome.command, "npx @biomejs/biome lint --error-on-warnings --only=suspicious/noConsole .");
+  assert.equal(biome.tool, "https://github.com/biomejs/biome");
+  // Без biome.json — прежний совет под язык.
+  const plain = blindAdvice(entry, { langs: new Set(["javascript"]), has_biome: false });
+  assert.match(plain.command, /^eslint /);
+  // У Biome правила нет вовсе (`none`) — прежний совет, а не выдуманная команда Biome.
+  const none = blindAdvice({ ...entry, biome_rules: "none" }, { langs: new Set(["javascript"]), has_biome: true });
+  assert.match(none.command, /^eslint /);
+});
+
+// --- свод виден Claude Code --------------------------------------------------------
+// Документация Claude Code (code.claude.com/docs/en/memory, раздел AGENTS.md, сверено
+// 2026-09-11): «Claude Code reads CLAUDE.md, not AGENTS.md». Рекомендовано: CLAUDE.md с
+// @AGENTS.md либо символическая ссылка. Проект, где Claude Code настроен, а свод лежит только
+// в AGENTS.md, пишет правила агенту, который их не читает.
+test("свод в AGENTS.md виден Claude Code только через CLAUDE.md с @AGENTS.md", () => {
+  const base = { agents: true, claude: null, claudeLink: false, dotClaude: false };
+  assert.equal(claudeSeesRules(base), null, "Claude Code не настроен — молчим: Codex и Cursor читают AGENTS.md сами");
+  assert.equal(claudeSeesRules({ ...base, dotClaude: true }), "missing");
+  assert.equal(claudeSeesRules({ ...base, claude: "# Rules\n\nSee AGENTS.md for everything.\n" }), "noImport",
+    "упоминание словами — не подключение: файл Claude Code в контекст не загрузит");
+  assert.equal(claudeSeesRules({ ...base, claude: "# CLAUDE.md\n\n@AGENTS.md\n" }), null);
+  assert.equal(claudeSeesRules({ ...base, claude: "@../AGENTS.md\n" }), null, "из .claude/CLAUDE.md свод подключают на уровень выше");
+  assert.equal(claudeSeesRules({ ...base, claude: "Правила — в `@AGENTS.md`.\n" }), "noImport",
+    "в обратных кавычках @ не подключает — так в документации");
+  assert.equal(claudeSeesRules({ ...base, claude: "x", claudeLink: true }), null, "ссылка на AGENTS.md — тот же файл");
+  assert.equal(claudeSeesRules({ ...base, agents: false, dotClaude: true }), null, "AGENTS.md нет — подключать нечего");
+});

package/tool/selfcheck/units-verdict.mjs

@@ -0,0 +1,76 @@
+// tool/selfcheck/units-verdict.mjs — вердикт пробы: «поймано» только ПО ДЕЛУ.
+//
+// ОТДЕЛЬНЫМ ФАЙЛОМ: units-probe.mjs у предела в 500 строк, и шов настоящий — там разбор
+// истории и план пробы, здесь то, на чём держится главное обещание пробы.
+//
+// ЗАЧЕМ. Отзыв с живого проекта 2026-09-11 (Amplifie, TypeScript на Biome): класс «цвет из
+// токена темы» проба отметила пойманным линтером, хотя Biome цвета не проверяет. Подсаженный
+// кусок сломал форматирование — упал форматтер. Вердикт считал «покраснел» равным «поймал»:
+// код возврата сравнивался, вывод выбрасывался. Итог — «every applicable class is caught by
+// something», ложная уверенность ровно в сторону самоуспокоения. К себе комплект был мягче,
+// чем к проекту: от чужого гейта мы требуем покраснеть НА БРАКЕ, а свой вердикт этого не
+// проверял.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { namesPlant, probeVerdictPaired, catchVerdict } from "../lib/history.mjs";
+
+test("назвал подсаженный файл: путь появился в выводе после подсадки", () => {
+  assert.equal(namesPlant("", "src/ui/card.tsx:12:5 lint/style/noColorLiteral", "src/ui/card.tsx"), true);
+  // Любая форма пути: относительная с ./, абсолютная из песочницы, с обратными слешами Windows.
+  assert.equal(namesPlant("", "./src/ui/card.tsx:3 print found", "src/ui/card.tsx"), true);
+  assert.equal(namesPlant("", "/tmp/aqk-probe-x/src/ui/card.tsx:3", "src/ui/card.tsx"), true);
+  assert.equal(namesPlant("", "src\\ui\\card.tsx(3,1): error", "src/ui/card.tsx"), true);
+});
+
+test("не назвал: упал по своей причине — форматтер, чужой файл, общий итог", () => {
+  assert.equal(namesPlant("", "Formatter would have printed the following content.\nFound 1 error.", "src/ui/card.tsx"), false);
+  assert.equal(namesPlant("", "src/other.tsx:1 error", "src/ui/card.tsx"), false);
+  // Файл упоминался и до подсадки столько же раз — нового ничего не сказано.
+  assert.equal(namesPlant("src/ui/card.tsx:1 warn", "src/ui/card.tsx:1 warn", "src/ui/card.tsx"), false);
+});
+
+const pairs = (before, after) => ({
+  before: before.map(([name, code]) => ({ name, code })),
+  after: after.map(([name, code, named]) => ({ name, code, named })),
+});
+
+test("покраснел, но подсаженного файла не назвал — «неизвестно», а не «поймано»", () => {
+  const { before, after } = pairs([["lint", 0], ["units", 0]], [["lint", 1, false], ["units", 0]]);
+  const r = probeVerdictPaired(before, after);
+  assert.equal(r.verdict, "unknown");
+  assert.equal(r.unattributed, 1);
+  assert.equal(r.caught, 0);
+});
+
+test("поймал по делу хоть один — «поймано»; безымянное падение соседа этого не отменяет", () => {
+  const { before, after } = pairs([["fmt", 0], ["lint", 0]], [["fmt", 1, false], ["lint", 1, true]]);
+  const r = probeVerdictPaired(before, after);
+  assert.equal(r.verdict, "caught");
+  assert.equal(r.caught, 1);
+});
+
+test("без сведений о выводе (старые вызовы) поведение прежнее", () => {
+  const { before, after } = pairs([["lint", 0]], [["lint", 1, undefined]]);
+  assert.equal(probeVerdictPaired(before, after).verdict, "caught");
+});
+
+// ИМЕНИ ФАЙЛА МАЛО. Biome, падая на форматировании, тоже называет файл: «src/card.tsx format».
+// Отличить «упал на браке» от «упал на подсадке» можно только ПАРОЙ — ровно тем, чем мы проверяем
+// чужие гейты: в то же место кладётся ЗЕЛЁНЫЙ образец той же записи. Краснеет и на нём — гейт
+// падает от самой подсадки (форматирование, синтаксис), поимка не доказана.
+test("пара: на красном назвал файл, на зелёном молчит — поймал", () => {
+  const red = { code: 1, out: "src/card.tsx:3 lint/noColorLiteral" };
+  const green = { code: 0, out: "" };
+  assert.equal(catchVerdict("", red, green, "src/card.tsx"), "caught");
+});
+
+test("пара: краснеет и на зелёном, называя тот же файл, — падает от подсадки, не поймал", () => {
+  const red = { code: 1, out: "src/card.tsx format ━━━ Formatter would have printed" };
+  const green = { code: 1, out: "src/card.tsx format ━━━ Formatter would have printed" };
+  assert.equal(catchVerdict("", red, green, "src/card.tsx"), "planting");
+});
+
+test("пара: файла не назвал — «безымянно»; зелёного образца под расширение нет — судим по имени", () => {
+  assert.equal(catchVerdict("", { code: 1, out: "Found 1 error." }, { code: 0, out: "" }, "src/a.py"), "nameless");
+  assert.equal(catchVerdict("", { code: 1, out: "src/a.py:1 T201" }, null, "src/a.py"), "caught");
+});