agent-quality-kit 0.8.0 → 0.10.0

package/tool/selfcheck/smoke/_fixture.mjs

@@ -0,0 +1,89 @@
+// tool/selfcheck/smoke/_fixture.mjs — общая оснастка проверок, гоняющих сам инструмент.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫЙ ФАЙЛ. В `smoke.sh` фикстура «временный проект под git» написана сорок раз
+// подряд одними и теми же четырьмя строками. Это не похожие строки, а ОДНО знание в сорока
+// местах: меняется устройство подопытного проекта — правится сорок мест, и они расходятся.
+//
+// ЧТО ЗДЕСЬ ЗАКРЫТО, кроме дублирования (всё — из разборов флейков и из нашего же опыта):
+//   · СВОЙ каталог на проверку и уборка после неё — через `t.after`, а не «не забыть rm»;
+//   · ТАЙМАУТ на каждый запуск: висящий подпроцесс иначе держит конвейер до его предела;
+//   · ГЕРМЕТИЧНОСТЬ: HOME и TMPDIR в песочнице, сеть выключена. Прогон обязан давать один
+//     ответ на любой машине и в любой день — иначе зелёное значит «сегодня совпало».
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const CLI = join(ROOT, "tool", "program.mjs");
+
+// Предел на один запуск. Тридцать секунд — с запасом: самый долгий наш прогон в фикстуре
+// (`start` со всеми записями) укладывается в единицы секунд. Предел нужен не ради скорости,
+// а ради того, чтобы висящий процесс называл себя, а не съедал бюджет задания молча.
+const TIMEOUT_MS = 30000;
+
+function env(home) {
+  return {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home,
+    TMPDIR: join(home, "tmp"),
+    AQK_LANG: "ru",
+    // Сеть в тестах — отдельный класс флейков, и у нас она включалась ТОЛЬКО вне конвейера:
+    // локально проверки были сетевыми, в конвейере нет. Две разные среды по построению.
+    AQK_UPDATE: "0",
+  };
+}
+
+// Подопытный проект: свой каталог, свой git, свой дом. Файлы задаются картой «путь → текст»,
+// потому что имя файла в такой проверке — часть утверждения, а не деталь.
+function project(t, files = {}, { git = true } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "aqk-smoke-"));
+  const home = join(dir, ".home");
+  mkdirSync(join(home, "tmp"), { recursive: true });
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  for (const [rel, text] of Object.entries(files)) {
+    const full = join(dir, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, text, "utf8");
+  }
+  const p = { dir, home };
+  if (git) {
+    run(p, "git", ["init", "-q", "."]);
+    run(p, "git", ["config", "user.email", "t@t"]);
+    run(p, "git", ["config", "user.name", "t"]);
+  }
+  return p;
+}
+
+// Запуск чего угодно в каталоге проекта. Возвращается И код, И вывод: проверка, смотрящая
+// только на код, не умеет объяснить провал, а смотрящая только на вывод — не умеет заметить,
+// что команда не роняет прогон.
+function run({ dir, home }, cmd, args = []) {
+  const r = spawnSync(cmd, args, {
+    cwd: dir, encoding: "utf8", timeout: TIMEOUT_MS, env: env(home),
+  });
+  return { code: r.status, out: `${r.stdout || ""}${r.stderr || ""}` };
+}
+
+const aqk = (p, ...args) => run(p, process.execPath, [CLI, ...args]);
+
+// ПОЧЕМУ ГЕЙТ ЗОВЁТСЯ ТОЧКОЙ, А НЕ ПУТЁМ, И ПОЧЕМУ ПУТЬ ЧЕРЕЗ КОСУЮ.
+// Node на Windows отдаёт `C:\Users\…\Temp\aqk-smoke-x`, а Git Bash живёт в POSIX-мире и
+// такого пути не знает: проверка искала спецификации в несуществующем каталоге, не находила
+// ничего и выходила с нулём — то есть краснела не на дефекте, а на переносимости. Поймано
+// конвейером на windows-задании в тот же день, когда файл был написан.
+// Лечится двумя приёмами сразу: каталог отдаётся как «.» вместе с cwd (переводить нечего),
+// а путь до самого скрипта — с прямыми косыми, их Git Bash понимает.
+const posix = (p) => String(p).replace(/\\/g, "/");
+// Подкаталог нужен там, где проверяется не сам проект, а его клон: мелкий клон предложения
+// изменений ведёт себя иначе, чем полная история, и это отдельный класс отказов.
+const gate = (p, name, sub = ".") =>
+  run(p, "bash", [posix(join(ROOT, "kit", "gates", name, "check.sh")), sub]);
+
+// Наружу — только то, что зовут проверки. `ROOT` и `CLI` остаются внутри: экспорт, который
+// никто не берёт, читается как часть договора и мешает менять внутренности — поймал наш же
+// dead-code через минуту после того, как файл был написан. `run` вернулся, когда появилась
+// проверка, которой нужен сырой git: экспорт заводится под потребителя, а не про запас.
+export { project, run, aqk, gate };

package/tool/selfcheck/smoke/api-contract.test.mjs

@@ -0,0 +1,79 @@
+// Проверки про договор с чужим кодом: кто держит спецификацию API и умеет ли держатель
+// провалиться. Переехали из smoke.sh 2026-09-09 первыми — как доказательство переезда.
+//
+// ЗАМЕР, ИЗ КОТОРОГО ОНИ ВЗЯЛИСЬ. Стенд, где сервер врёт в каждом поле ответа:
+//   spectral (spectral:oas)             код 0  — нет контакта, описания, тегов
+//   schemathesis, умолчания             код 1  — три нарушения схемы в ответах
+//   schemathesis -c not_a_server_error  код 0  — «18 из 18 прошли»
+//   oasdiff breaking без --fail-on      код 0  — печатает ломающую правку и молчит кодом
+import test from "node:test";
+import assert from "node:assert/strict";
+import { project, aqk, gate } from "./_fixture.mjs";
+
+const SPEC = "openapi: 3.0.3\ninfo: { title: t, version: 1.0.0 }\npaths: {}\n";
+const workflow = (steps) =>
+  `name: ci\non: [push]\njobs:\n  contract:\n    runs-on: ubuntu-latest\n    steps:\n${steps}`;
+
+// ЛОВУШКА, ИЗ-ЗА КОТОРОЙ ЗАМЕР ЧУТЬ НЕ ОКАЗАЛСЯ ЛОЖНО-ЗЕЛЁНЫМ: шаг с именем «Spec lint»
+// краснеет не потому, что узнали инструмент, а потому что в имени есть слово-примета.
+// Поэтому здесь у шагов НЕТ слов-подсказок — проверяется опознание инструмента.
+test("обезвреженные проверки контракта API опознаются как проверки", (t) => {
+  const p = project(t, {
+    ".github/workflows/api.yml": workflow(
+      "      - name: соответствие сервера схеме\n" +
+      "        continue-on-error: true\n" +
+      "        run: schemathesis run openapi.yaml --url http://localhost:8000\n" +
+      "      - name: ломающие изменения\n" +
+      "        continue-on-error: true\n" +
+      "        run: oasdiff breaking base.yaml openapi.yaml --fail-on ERR\n" +
+      "      - name: ожидания потребителей\n" +
+      "        continue-on-error: true\n" +
+      "        run: pact-broker can-i-deploy --pacticipant web\n"),
+  });
+  const r = gate(p, "ci-actually-fails");
+  assert.equal(r.code, 1, `три шага под continue-on-error прошли как чистые:\n${r.out}`);
+});
+
+// У записи две красные ветки, и вторая тоньше первой. Проверяются ОБЕ формы сужения и
+// мутация: снял сужение — гейт обязан замолчать, иначе краснеет он не от этого.
+test("арбитр, который не может провалиться, краснеет в обеих формах", (t) => {
+  const mk = (tail) => ({
+    "openapi.yaml": SPEC,
+    ".github/workflows/ci.yml": workflow(
+      `      - run: schemathesis run openapi.yaml --url http://localhost:8000${tail}\n`),
+  });
+  for (const narrow of [" -c not_a_server_error", " --checks not_a_server_error"]) {
+    const p = project(t, mk(narrow));
+    assert.equal(gate(p, "api-contract-has-arbiter").code, 1, `сужение «${narrow}» не опознано`);
+  }
+  const full = project(t, mk(""));
+  assert.equal(gate(full, "api-contract-has-arbiter").code, 0, "полный арбитр покраснел");
+
+  const loud = project(t, {
+    "openapi.yaml": SPEC,
+    ".github/workflows/ci.yml": workflow(
+      "      - run: schemathesis run openapi.yaml --url http://localhost:8000\n" +
+      "      - run: oasdiff breaking base.yaml openapi.yaml\n"),
+  });
+  assert.equal(gate(loud, "api-contract-has-arbiter").code, 1,
+    "oasdiff без --fail-on печатает находки и выходит с нулём — это не проверка");
+});
+
+// НАЙДЕНО АУДИТОМ ФИЧ, а не образцами: красный и зелёный образцы лежат по одному, а в
+// настоящем проекте записи стоят рядом — и соседняя `ci-actually-fails` держит в своём
+// check.sh список запускалок со ВСЕМИ инструментами про API разом. Проверка находила её и
+// выдавала ложное ЗЕЛЁНОЕ там, где договор не держал никто.
+test("держателем не считается определение соседней записи", (t) => {
+  const p = project(t, {
+    "src/a.py": "def s():\n    return 1\n",
+    "openapi.yaml": SPEC,
+    ".github/workflows/ci.yml": workflow("      - run: pytest\n"),
+  });
+  aqk(p, "init");
+  aqk(p, "add", "ci-actually-fails");
+  aqk(p, "add", "api-contract-has-arbiter");
+  const r = gate(p, "api-contract-has-arbiter");
+  assert.equal(r.code, 1, `договор без держателя прошёл зелёным:\n${r.out}`);
+  // Второй дефект того же прогона: `find` без завершающего -print печатал обойдённые каталоги.
+  assert.doesNotMatch(r.out, /\.git|\.aqk/, `в списке спецификаций каталоги:\n${r.out}`);
+});

package/tool/selfcheck/smoke/commit-report.test.mjs

@@ -0,0 +1,47 @@
+// Мини-отчёт в коммите: где его требовать, а где состав коммита определить нельзя.
+//
+// НАЙДЕНО КОНВЕЙЕРОМ 2026-09-09. Коммит, трогающий ТОЛЬКО журнал, отчёта не требует — сама
+// запись и есть отчёт. Локально так и было. В конвейере тот же коммит покраснел, и причина
+// тоньше, чем кажется:
+//   · при разборе предложения изменений GitHub выкладывает синтетический коммит слияния,
+//     и гейт правильно спрашивает второго родителя — коммит автора;
+//   · но выкладка идёт МЕЛКИМ клоном, и родителя второго родителя в нём нет;
+//   · `git show --name-only` на коммите без родителя считает его корневым и выдаёт ВСЁ дерево;
+//   · значит «трогает только журнал» перестаёт срабатывать — молча, — и гейт требует отчёт там,
+//     где не должен.
+// Проверено опытом: глубина 2 — красный, глубина 3 — чисто.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { project, run, gate } from "./_fixture.mjs";
+
+function repoWithJournalMerge(t) {
+  const p = project(t, {
+    "incidents/README.md": "# журнал\n",
+    "src/a.py": "код\n",
+    ".aqk.yml": "lessons: incidents\n",
+  });
+  run(p, "git", ["add", "-A"]);
+  run(p, "git", ["commit", "-q", "-m", "feat: первый", "-m", "Сделано: завёл", "-m", "Не уверен: ни в чём"]);
+  run(p, "git", ["checkout", "-q", "-b", "feature"]);
+  run(p, "bash", ["-c", "printf '## запись\\n' >> incidents/README.md"]);
+  run(p, "git", ["add", "-A"]);
+  // Тело НАРОЧНО без «Сделано:»: если освобождение для журнала перестанет работать, гейт
+  // покраснеет — то есть проверка умеет отличить исправное от сломанного.
+  run(p, "git", ["commit", "-q", "-m", "docs: урок", "-m", "Не уверен: ничего не сломано"]);
+  const main = run(p, "bash", ["-c", "git checkout -q master 2>/dev/null || git checkout -q main; git rev-parse --short HEAD"]);
+  run(p, "git", ["merge", "-q", "--no-ff", "feature", "-m", `Merge feature into ${main.out.trim()}`]);
+  return p;
+}
+
+test("коммит только в журнал не требует отчёта и в мелком клоне слияния", (t) => {
+  const p = repoWithJournalMerge(t);
+  assert.equal(gate(p, "commit-explains-itself").code, 0, "полная история: журнальный коммит покраснел");
+
+  // Ровно то, что делает конвейер при разборе предложения изменений.
+  run(p, "bash", ["-c", "git clone -q --depth 2 file://$PWD shallow2 2>/dev/null"]);
+  const r = gate(p, "commit-explains-itself", "shallow2");
+  assert.equal(r.code, 0, `мелкий клон: гейт требует отчёт там, где состав определить нельзя:\n${r.out}`);
+  // Молчать в этом случае нельзя: пропуск обязан называть себя, иначе выключенная проверка
+  // неотличима от работающей — тот самый класс, ради которого весь комплект.
+  assert.match(r.out, /не определить|журнал/, `пропуск не назвал причину:\n${r.out}`);
+});

package/tool/selfcheck/smoke/verdict.test.mjs

@@ -0,0 +1,40 @@
+// Прогон обязан называть свой вердикт СЛОВАМИ, а не только кодом возврата.
+//
+// НАЙДЕНО АУДИТОМ ФИЧ 2026-09-09. `doctor --run` выходил с единицей и в конце не говорил ни
+// слова о причине: она оставалась в шапке, а внизу человек видел список зелёных гейтов и шёл
+// искать несуществующую поломку. С `--min` вердикт печатался всегда, без него — никогда.
+// Обратная сторона нашего же принципа: молчание неотличимо не только от успеха, но и от отказа.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { project, aqk } from "./_fixture.mjs";
+
+test("прогон называет свой вердикт словами в обоих исходах", (t) => {
+  const p = project(t, { "src/a.py": "def s():\n    return 1\n" });
+  aqk(p, "init");
+  // Гейт объявляется ПРЯМО, а не через `add`, и это не лень. `add` выбирает рецепт по тому,
+  // что установлено на машине: где есть ruff, у `todo-without-task` берётся родной
+  // `ruff check --select FIX,TD`, где нет — переносимый. Значит один и тот же проект получает
+  // РАЗНУЮ объявленную команду на разных машинах, и проверка про ВЕРДИКТ начинала зависеть от
+  // чужого инструмента. Поймано конвейером: локально зелено, на раннере красно.
+  // Здесь проверяется строка вердикта, а не поведение записи каталога, — гейту довольно быть
+  // заведомо тихим.
+  const man = join(p.dir, ".aqk.yml");
+  writeFileSync(man, readFileSync(man, "utf8").replace(/^gates:\s*$/m, 'gates:\n  тихий: "true"'), "utf8");
+
+  // .gitignore нет — прогон красный, и обязан сказать, из-за чего именно.
+  const red = aqk(p, "doctor", "--run");
+  // Сообщение утверждения обязано нести ВЕСЬ хвост: проверка, которая говорит только «не
+  // совпало», отправляет читателя гадать — ровно то, за что мы ругаем чужие проверки.
+  const redTail = red.out.trimEnd().split("\n").slice(-6).join("\n");
+  assert.notEqual(red.code, 0, `прогон без .gitignore прошёл зелёным:\n${redTail}`);
+  assert.match(redTail, /красн/, `вердикт не назван в конце вывода (код ${red.code}):\n${redTail}`);
+
+  // Причина устранена — и «ничего не сказал» обязано отличаться от «всё проверено».
+  writeFileSync(join(p.dir, ".gitignore"), "x\n", "utf8");
+  const green = aqk(p, "doctor", "--run");
+  const greenTail = green.out.trimEnd().split("\n").slice(-6).join("\n");
+  assert.equal(green.code, 0, `прогон остался красным:\n${greenTail}`);
+  assert.match(greenTail, /зелён/, `успех не назван словами:\n${greenTail}`);
+});