agent-quality-kit 0.11.0 → 0.12.0

package/tool/selfcheck/units-probe.mjs

@@ -3,7 +3,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { isFix, fixHotspots, probeSummary, probeVerdictPaired, countProbe } from "../lib/history.mjs";
-import { probeableGates, gatesState, extAlternatives, planProbeGates, isCode } from "../commands/probe.mjs";
+import { probeableGates, gatesState, extAlternatives, planProbeGates, blindAdvice, isCode } from "../commands/probe.mjs";
 
 // Признак починки берётся из ТЕМЫ коммита, а не из тела: тема — единственное, что пишут все,
 // и единственное, что видно в `git log --oneline`. Три написания, потому что репозитории
@@ -220,6 +220,21 @@ test("парный вердикт: гейт позеленел от подсад
   assert.equal(probeVerdictPaired(before, after).verdict, "unknown");
 });
 
+// Гейт работал ДО подсадки и сломался ОТ неё. Он мог быть тем самым ловцом — «никто не ловит»
+// о нём сказать нельзя. Найдено пробой на самом комплекте 2026-09-11: образец лёг на место
+// kit/gates/_skip.sh, общей библиотеки двенадцати гейтов, все двенадцать вышли с кодом 2 —
+// включая gate-not-weakened, который в отдельной папке этот образец ловит. Остальные молчали,
+// и проба назвала класс слепым; doctor повторил это человеку жирным.
+test("парный вердикт: подсадка сломала работавший гейт — «не смогли», а не «слеп»", () => {
+  const { before, after } = pairs([["lint", 0], ["units", 0]], [["lint", 2], ["units", 0]]);
+  const r = probeVerdictPaired(before, after);
+  assert.equal(r.verdict, "unknown");
+  assert.equal(r.brokenByPlant, 1);
+  // Поимка соседом остаётся поимкой: знание получено, и сломанный гейт его не отменяет.
+  const other = pairs([["lint", 0], ["units", 0]], [["lint", 2], ["units", 1]]);
+  assert.equal(probeVerdictPaired(other.before, other.after).verdict, "caught");
+});
+
 test("парный вердикт: гейтов нет вовсе", () => {
   assert.equal(probeVerdictPaired([], []).verdict, "unknown");
 });
@@ -358,3 +373,91 @@ test("счёт непокрытого: исходы разложены по св
 test("счёт непокрытого: пусто не роняет", () => {
   assert.deepEqual(countProbe([]), { blindClasses: 0, caughtClasses: 0, unknownClasses: 0, probes: 0 });
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Непокрытый класс объясняется, а не называется. Написано ДО кода 2026-09-10.
+//
+// ЗАЧЕМ. Проба находит настоящие дыры — и печатает про них «close it: aqk add <имя>», то есть
+// «поставь нашу штуку». Человек, который видит комплект впервые, закрывает окно.
+//
+// А готовая однострочная команда под его стек У НАС УЖЕ ЛЕЖИТ, в `recipes` записи каталога. Мы
+// её просто не показываем. Замер руками на `requests` (самый скачиваемый python-пакет): в
+// `src/requests/utils.py` — 75 коммитов-починок; дописана функция с `except Exception: pass`;
+// их собственные `ruff` и `pytest` дали 0 и на чистой копии, и на подсаженной. Строка, которая
+// бы это поймала, — `ruff check --select BLE,TRY400,SIM105 .` — лежала в нашем каталоге всё это
+// время.
+//
+// Польза обязана быть видна ДО установки комплекта: скопировал строку, увидел находки у себя —
+// и только тогда думаешь, ставить ли нас. Отчёт, который учит, а не отчитывается.
+test("совет по непокрытому классу даёт команду под стек, а не «поставь нас»", () => {
+  const entry = {
+    slug: "swallowed-error",
+    recipes: {
+      any: "bash {gate}/check.sh {dir}",
+      python: "ruff check --select BLE,TRY400,SIM105 {dir}",
+    },
+  };
+  const a = blindAdvice(entry, { langs: new Set(["python"]) }, { file: "src/requests/utils.py", fixes: 75 });
+  assert.equal(a.command, "ruff check --select BLE,TRY400,SIM105 .",
+    "команда обязана быть готовой к вставке: {dir} подставлен, {gate} не годится");
+  assert.equal(a.file, "src/requests/utils.py");
+  assert.equal(a.fixes, 75);
+});
+
+// Переносимый рецепт зовёт наш файл — вставить его человеку, у которого комплекта нет, нельзя.
+// Тогда команды нет, и совет остаётся один: поставить запись.
+test("совет: переносимый рецепт вставить некуда — команда не выдумывается", () => {
+  const entry = { slug: "x", recipes: { any: "bash {gate}/check.sh {dir}" } };
+  assert.equal(blindAdvice(entry, { langs: new Set(["python"]) }, { file: "a.py", fixes: 1 }).command, null);
+});
+
+test("совет: у стека нет своего рецепта — команды нет", () => {
+  const entry = { slug: "x", recipes: { python: "ruff check {dir}" } };
+  assert.equal(blindAdvice(entry, { langs: new Set(["go"]) }, { file: "a.go", fixes: 2 }).command, null);
+});
+
+// Python-проекту показывалась ссылка на eslint и knip: поле `tool` у записи общее на все языки.
+// Совет, в котором половина не про тебя, читается весь как «не про тебя».
+test("совет: адрес инструмента — того, которым начинается команда", () => {
+  const entry = {
+    slug: "dead-code",
+    tool: "https://github.com/jendrikseipp/vulture · https://github.com/webpro-nl/knip",
+    recipes: { python: "vulture --min-confidence 60 {dir}", javascript: "npx knip" },
+  };
+  assert.equal(blindAdvice(entry, { langs: new Set(["python"]) }).tool, "https://github.com/jendrikseipp/vulture");
+  // Команды нет или имя не совпало — весь список: лучше лишняя ссылка, чем ни одной.
+  assert.equal(blindAdvice(entry, { langs: new Set(["go"]) }).tool, entry.tool);
+  assert.equal(blindAdvice({ slug: "x" }, { langs: new Set() }).tool, null);
+});
+
+test("совет: пустая запись не роняет разбор", () => {
+  assert.equal(blindAdvice({}, { langs: new Set() }, {}).command, null);
+  assert.equal(blindAdvice({}, {}, {}).command, null);
+});
+
+// Безъязыковой родной рецепт годится в совет так же, как языковой: секреты ищутся в любом
+// файле, и именно они чаще всего оказывались в непокрытых на чужих проектах.
+test("совет: безъязыковой родной рецепт тоже даёт команду", () => {
+  const entry = { slug: "secrets-not-in-code",
+    recipes: { native: "gitleaks dir --no-banner {dir}", any: "bash {gate}/check.sh {dir}" } };
+  const a = blindAdvice(entry, { langs: new Set(["python"]) }, { file: "a.py", fixes: 9 });
+  assert.equal(a.command, "gitleaks dir --no-banner .");
+});
+
+// Из совета вычищается то, что относится к НАМ, а не к его проекту. Исключение наших красных
+// образцов (`gates/*/red`) нужно установленному гейту — рядом с ним лежат образцы. Человеку,
+// который команду только копирует, эти флаги бессмысленны и подрывают доверие: он видит, что
+// инструмент говорит про какие-то чужие каталоги, которых у него нет.
+test("совет: исключения наших образцов в команду не попадают", () => {
+  const entry = { slug: "no-print-in-prod", recipes: { javascript:
+    "eslint --no-config-lookup --ignore-pattern 'gates/*/red/**' --ignore-pattern 'gates/*/green/**' --rule '{\"no-console\":\"error\"}' {dir}" } };
+  const a = blindAdvice(entry, { langs: new Set(["javascript"]) }, {});
+  assert.ok(!a.command.includes("gates/"), `в совете остались наши каталоги: ${a.command}`);
+  assert.ok(a.command.includes("no-console"), "правило потерялось вместе с исключениями");
+  assert.ok(a.command.startsWith("eslint "), a.command);
+});
+
+test("совет: команда без наших исключений не портится", () => {
+  const entry = { slug: "x", recipes: { python: "ruff check --select T20 {dir}" } };
+  assert.equal(blindAdvice(entry, { langs: new Set(["python"]) }, {}).command, "ruff check --select T20 .");
+});

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 } from "../lib/repo.mjs";
+import { triggerVerdict, recipeFor, EXT_LANG, whichSync, browserServerAdvice, MARKS, isApiSpec, startWith } from "../lib/repo.mjs";
+import { proposeGates } from "../lib/adopt.mjs";
 import { CATALOGS, L } from "../i18n/index.mjs";
 import { dirname } from "node:path";
 
@@ -162,3 +163,124 @@ test("у каждого признака репозитория есть объ
     // запись каталога, выключенная навсегда и молча. Сторожим ту сторону, которая ломает.
   }
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Чужие проверки, которые у проекта УЖЕ есть. Написано ДО кода 2026-09-10.
+//
+// ЗАЧЕМ. Поставил комплект в `express` — проект с eslint, mocha и конвейером — и первое, что он
+// увидел: двадцать крестов подряд и «держит машина 0». Это неправда с его точки зрения: его
+// проверки держат, просто мы считаем только СВОИ записи.
+//
+// Мы видим, что конвейер ЕСТЬ (`has_ci`), но не читаем, что в нём. Человек должен вручную
+// переписать в манифест то, что мы могли прочитать сами. Отсюда и «не понимает, что хорошо»:
+// хорошее у него уже есть, а мы о нём молчим.
+//
+// Предлагаем, а не объявляем: гейт, вписанный без спроса, — это чужое решение в чужом файле.
+test("чужие проверки: из package.json берутся test, lint и проверка типов", () => {
+  const pkg = JSON.stringify({ scripts: {
+    test: "mocha", lint: "eslint .", typecheck: "tsc --noEmit",
+    build: "rollup -c", start: "node server.js", prepare: "husky",
+  } });
+  const got = proposeGates({ "package.json": pkg });
+  assert.deepEqual(got.map((g) => g.name).sort(), ["lint", "test", "typecheck"]);
+  assert.equal(got.find((g) => g.name === "test").cmd, "npm test");
+  assert.equal(got.find((g) => g.name === "lint").cmd, "npm run lint");
+});
+
+// `npm test` и `npm run test` — разные написания одного; берём каноничное. А `build` и `start`
+// проверками не являются: они собирают и запускают, а не судят.
+test("чужие проверки: сборка и запуск проверками не считаются", () => {
+  const pkg = JSON.stringify({ scripts: { build: "tsc", start: "node .", dev: "vite" } });
+  assert.deepEqual(proposeGates({ "package.json": pkg }), []);
+});
+
+// Makefile — вторая по частоте точка входа, и в python-проектах чаще первая.
+test("чужие проверки: цели Makefile тоже видны", () => {
+  const mk = "install:\n\tpip install -e .\n\ntest:\n\tpytest -q\n\nlint:\n\truff check .\n";
+  const got = proposeGates({ Makefile: mk });
+  assert.deepEqual(got.map((g) => g.name).sort(), ["lint", "test"]);
+  assert.equal(got.find((g) => g.name === "test").cmd, "make test");
+});
+
+test("чужие проверки: нечего предложить — пустой список, а не выдумка", () => {
+  assert.deepEqual(proposeGates({}), []);
+  assert.deepEqual(proposeGates({ "package.json": "{ не json" }), []);
+});
+
+// Источник называется: человек обязан видеть, ОТКУДА мы это взяли, иначе предложение
+// неотличимо от нашей догадки.
+test("чужие проверки: у каждого предложения назван источник", () => {
+  const got = proposeGates({ "package.json": JSON.stringify({ scripts: { test: "jest" } }) });
+  assert.equal(got[0].source, "package.json");
+});
+
+// Python-проекты. Замер 2026-09-11 на восьми живых (requests, click, flask, httpx, black,
+// fastapi, pydantic, rich): package.json нет ни у кого, Makefile у трёх — и пятеро из восьми
+// слышали «у вас ничего нет». А `.pre-commit-config.yaml` лежит у семи, tox — у пяти (у click и
+// flask в pyproject.toml), у httpx — исполняемые scripts/test и scripts/check.
+// Куски ниже сняты с этих репозиториев, а не придуманы.
+test("чужие проверки: pre-commit предлагается целиком, хуки названы поимённо", () => {
+  const cfg = "repos:\n  - repo: https://github.com/pre-commit/pre-commit-hooks\n    hooks:\n" +
+    "      - id: check-yaml\n      - id: end-of-file-fixer\n" +
+    "  - repo: https://github.com/astral-sh/ruff-pre-commit\n    hooks:\n    - id: ruff-check\n";
+  const got = proposeGates({ ".pre-commit-config.yaml": cfg });
+  assert.equal(got.length, 1);
+  assert.equal(got[0].cmd, "pre-commit run --all-files");
+  assert.match(got[0].source, /ruff-check/, "человек видит, ЧТО там стоит, а не только файл");
+});
+
+test("чужие проверки: из tox берутся окружения-проверки, а не матрица версий", () => {
+  const ini = "[tox]\nenvlist = py{310,311}-{default}\n\n[testenv]\ncommands = pytest\n\n" +
+    "[testenv:lint]\ncommands = ruff check .\n\n[testenv:docs]\ncommands = sphinx-build\n\n[testenv:{,ci-}pypy3]\n";
+  assert.deepEqual(proposeGates({ "tox.ini": ini }).map((g) => g.cmd), ["tox -e lint"]);
+  // click и flask держат tox в pyproject.toml, новым синтаксисом.
+  const py = "[tool.tox]\nenv_list = [\"py3\"]\n\n[tool.tox.env.style]\ncommands = []\n\n" +
+    "[tool.tox.env.typing]\ncommands = []\n\n[tool.tox.env.docs]\ncommands = []\n";
+  const got = proposeGates({ "pyproject.toml": py });
+  assert.deepEqual(got.map((g) => g.cmd).sort(), ["tox -e style", "tox -e typing"]);
+  assert.equal(got[0].source, "pyproject.toml");
+});
+
+test("чужие проверки: исполняемые scripts/test и scripts/check — как у httpx", () => {
+  const got = proposeGates({ "scripts/test": "", "scripts/check": "", "scripts/publish": "" });
+  assert.deepEqual(got.map((g) => g.cmd).sort(), ["scripts/check", "scripts/test"]);
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// С чего начать: три записи вместо двадцати равнозначных крестов. Написано ДО кода.
+//
+// ЗАЧЕМ. После установки человек видит двадцать крестов одинаковой формы и не знает, за что
+// взяться. Двадцать одинаковых требований — это ноль требований: закрывают первое попавшееся
+// или не закрывают ничего.
+//
+// Порядок НЕ ПО НАШЕМУ ВКУСУ. Два признака, оба — факты, которые у нас уже есть:
+//   · запись родилась из настоящего отказа (`proof` ссылается на журнал шишек — тот же
+//     признак, которым каталог отделяет условную запись) — она про боль, которая случалась, а не про «хорошую практику»;
+//   · её можно закрыть ОДНОЙ ГОТОВОЙ КОМАНДОЙ — значит цена входа минутная.
+// Сначала то, что и больно, и дёшево.
+test("с чего начать: сперва рождённые из отказа и закрываемые одной командой", () => {
+  const list = [
+    { slug: "praktika", proof: "хорошая практика", recipes: { any: "bash {gate}/c.sh {dir}" } },
+    { slug: "bol-i-deshevo", proof: "incidents/README.md, 2026-09-01", recipes: { native: "gitleaks dir {dir}" } },
+    { slug: "bol-no-dorogo", proof: "incidents/README.md, 2026-08-02", recipes: { any: "bash {gate}/c.sh {dir}" } },
+    { slug: "deshevo", proof: "методичка", recipes: { python: "ruff check {dir}" } },
+  ];
+  assert.deepEqual(startWith(list, { langs: new Set(["python"]) }, 3).map((e) => e.slug),
+    ["bol-i-deshevo", "deshevo", "bol-no-dorogo"]);
+});
+
+test("с чего начать: список короче трёх не ломается", () => {
+  assert.deepEqual(startWith([], { langs: new Set() }, 3), []);
+  const one = [{ slug: "a", proof: "incidents/README.md", recipes: {} }];
+  assert.deepEqual(startWith(one, { langs: new Set() }, 3).map((e) => e.slug), ["a"]);
+});
+
+// Порядок обязан быть УСТОЙЧИВЫМ: одинаковый ввод — одинаковый ответ, иначе человек видит
+// разный совет на двух прогонах подряд и перестаёт верить обоим.
+test("с чего начать: при равенстве признаков порядок стабилен", () => {
+  const list = [
+    { slug: "b", proof: "incidents/README.md", recipes: {} },
+    { slug: "a", proof: "incidents/README.md", recipes: {} },
+  ];
+  assert.deepEqual(startWith(list, { langs: new Set() }, 2).map((e) => e.slug), ["a", "b"]);
+});

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, browserServerAdvice, MARKS } from "../lib/repo.mjs";
+import { triggerVerdict, recipeFor, pickRecipe, 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";
@@ -398,3 +398,36 @@ test("наборы файлов правил совпадают на обоих
 
 
 
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Рецепт, не привязанный к языку. Написано ДО кода 2026-09-10.
+//
+// ЗАЧЕМ. Ключи рецептов — языки: `python`, `javascript`, `go`. Это верно для линтеров, но
+// неверно для инструментов, которым язык безразличен. `secrets-not-in-code` объявлен
+// `always: true`, готовый аналог у него — `gitleaks`, и он ищет ключи в любом файле.
+//
+// Без такого ключа выбор один из двух, и оба плохие: продублировать `gitleaks` под восемь
+// языков (тот самый повтор, против которого у нас есть гейт) или оставить запись без родного
+// рецепта. Второе и было: замер на десяти проектах показал секреты в НЕПОКРЫТЫХ у axios и у
+// всех четырёх python-проектов — то есть там, где польза наибольшая, команды для вставки не
+// было.
+//
+// Порядок предпочтения: свой язык → безъязыковой родной → переносимый. Родной сильнее
+// переносимого (у `gitleaks` сотни форматов токенов и чтение истории), но только если его есть
+// чем выполнить: непоставленная программа даёт «not found», а это отсутствие сигнала, выданное
+// за успех.
+test("рецепт: безъязыковой родной берётся, когда своего языка нет", () => {
+  const rec = { recipes: { native: "true --scan", any: "bash {gate}/check.sh {dir}" } };
+  assert.equal(pickRecipe(rec, { langs: new Set(["python"]) }), "true --scan");
+});
+
+test("рецепт: свой язык сильнее безъязыкового", () => {
+  const rec = { recipes: { python: "true --py", native: "true --scan", any: "bash x {dir}" } };
+  assert.equal(pickRecipe(rec, { langs: new Set(["python"]) }), "true --py");
+});
+
+// Программы нет — родной не берётся ни в каком виде, иначе гейт встанет с «not found».
+test("рецепт: безъязыковой без программы уступает переносимому", () => {
+  const rec = { recipes: { native: "aqk-nesuschestvuyuschiy --scan", any: "bash {gate}/check.sh {dir}" } };
+  assert.equal(pickRecipe(rec, { langs: new Set(["python"]) }), "bash {gate}/check.sh {dir}");
+});