agent-quality-kit 0.10.1 → 0.12.0

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}");
+});