agent-quality-kit 0.2.5 → 0.3.0

package/tool/program.mjs

@@ -17,9 +17,11 @@
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { c, SELF } from "./lib/core.mjs";
+import { L } from "./i18n/index.mjs";
 import { cmdInit, cmdNote, cmdBlob, cmdStart } from "./commands/project.mjs";
 import { cmdDoctor } from "./commands/doctor.mjs";
 import { cmdAdd, cmdNew, cmdRatchet, cmdFind, cmdWhy } from "./commands/gates.mjs";
+import { cmdReport } from "./commands/report.mjs";
 
 // Разбор аргументов выполняется только при запуске файла как программы. При импорте —
 // а так его читают модульные проверки tool/selfcheck/units.mjs — CLI запускаться не должен.
@@ -63,19 +65,39 @@ if (IS_MAIN) {
     case "blob":
       await cmdBlob();
       break;
-    default:
+    case "report":
+      await cmdReport();
+      break;
+    default: {
+      // Ширина колонки считается, а не подбирается пробелами: строки в двух языках разной
+      // длины, и вручную выровненная справка на втором языке разъезжается.
+      const h = L.help;
+      const rows = [
+        [`${SELF} init`, h.init],
+        [`${SELF} init --force`, h.initForce],
+        [`${SELF} start`, h.start],
+        [`${SELF} doctor`, h.doctor],
+        [`${SELF} doctor --run`, h.doctorRun],
+        [`${SELF} add ${h.name}`, h.add],
+        [`${SELF} find "…"`, h.find],
+        [`${SELF} why "…"`, h.why],
+        [`${SELF} ratchet ${h.name}`, h.ratchet],
+        [`${SELF} new ${h.name}`, h.new],
+        [`${SELF} note "…"`, h.note],
+        [`${SELF} blob`, h.blob],
+        [`${SELF} report`, h.report],
+      ];
+      const width = Math.max(...rows.map(([cmdText]) => cmdText.length));
+      const lines = rows.map(([cmdText, text]) => `  ${c.bold(cmdText.padEnd(width))}   ${text}`);
       console.log(`
-  ${c.bold("aqk")} — оснастка для разработки с агентами
+  ${c.bold("aqk")} — ${h.tagline}
 
-    ${c.bold(`${SELF} init`)}            разложить правила и методички в текущий проект
-    ${c.bold(`${SELF} init --force`)}    перезаписать уже существующие файлы
-  ${c.bold(`${SELF} start`)}           кода ещё нет: сторожа дня 0 и порядок работы
-    ${c.bold(`${SELF} doctor`)}          проверить, что разложено и чего не хватает\n  ${c.bold(`${SELF} doctor --run`)}    ещё и запустить объявленные гейты\n  ${c.bold(`${SELF} add`)} <имя>       поставить гейт из каталога в проект\n  ${c.bold(`${SELF} find`)} "…"       есть ли уже такой гейт — сверка по намерению\n  ${c.bold(`${SELF} why`)} "…"        поймал ошибку — почему её не поймал сторож\n  ${c.bold(`${SELF} ratchet`)} <имя>   храповик: старые нарушения — долг, новые не пускать\n  ${c.bold(`${SELF} new`)} <имя>       заготовка своего гейта для каталога
-    ${c.bold(`${SELF} note`)} "…"        записать урок в общий журнал шишек
-    ${c.bold(`${SELF} blob`)}            собрать методички в один файл GOD_AI.md
+${lines.join("\n")}
 
-  ${c.dim("Без установки:  npx agent-quality-kit init")}
+  ${c.dim(h.noInstall)}
+  ${c.dim(h.language)}
   `);
       process.exit(cmd ? 1 : 0);
+    }
   }
 }

package/tool/selfcheck/gates.sh

@@ -33,9 +33,15 @@ for GATE in "$CAT"/*/; do
   PROOF="$(field "$YML" proof)"
   [ -n "$INTENT" ] || bad "$SLUG: пустое поле intent — по нему идёт дедупликация"
 
+  # Английское намерение обязательно для НАШЕГО каталога: программа печатает его тем, кто
+  # пришёл с англоязычной площадки, и запись без перевода показала бы им кириллицу. Для
+  # чужой записи, принесённой со стороны, поле остаётся необязательным — программа тогда
+  # покажет то, что есть. Требовать перевод от вкладчика значит закрыть вклад половине.
+  [ -n "$(field "$YML" intent_en)" ] || bad "$SLUG: нет intent_en — намерение на английском"
+
   # Заготовка от `aqk new` не должна проехать как запись: незаполненный гейт — мёртвое
   # правило, а мёртвое правило учит игнорировать и живые.
-  if grep -q 'ЗАПОЛНИ' "$YML" "$GATE/README.md" "$GATE/check.sh" 2>/dev/null; then
+  if grep -qE 'ЗАПОЛНИ|FILL IN|FILL_IN' "$YML" "$GATE/README.md" "$GATE/check.sh" 2>/dev/null; then
     bad "$SLUG: заготовка не заполнена — остались метки ЗАПОЛНИ"
     continue
   fi

package/tool/selfcheck/smoke.sh

@@ -13,6 +13,10 @@
 
 set -uo pipefail
 
+# Язык вывода закреплён: проверки ниже сверяют русский текст, а без этой строки они зависели бы
+# от локали машины — на англоязычном раннере зелёное стало бы красным без единой правки в коде.
+export AQK_LANG=ru
+
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 CLI="$ROOT/tool/program.mjs"
 PASS=0
@@ -527,6 +531,99 @@ else
 fi
 rm -rf "$SHDIR" "$CEDIR"
 
+# --- 32. вывод действительно на двух языках -----------------------------------
+# Сверка ключей каталогов (units.mjs) доказывает, что строки не разошлись, но не доказывает,
+# что выбор языка вообще доехал до вывода. Это проверяется только запуском.
+EN_OUT=$(AQK_LANG=en node "$CLI" 2>&1)
+RU_OUT=$(AQK_LANG=ru node "$CLI" 2>&1)
+if printf '%s' "$EN_OUT" | grep -q "install a gate from the catalogue" &&
+   ! printf '%s' "$EN_OUT" | grep -q '[а-яА-ЯёЁ]' &&
+   printf '%s' "$RU_OUT" | grep -q "поставить гейт из каталога"; then
+  ok "справка печатается на двух языках, в английской нет кириллицы"
+else
+  bad "выбор языка не доехал до вывода" "$(printf '%s' "$EN_OUT" | head -4)"
+fi
+
+# --- 33. ссылка на репозиторий ведёт в репозиторий -----------------------------
+# Ссылку собирали из имени пакета. Когда имя стало коротким («agent-quality-kit» вместо
+# «github:владелец/репозиторий»), просьба про звезду поехала на github.com/agent-quality-kit —
+# несуществующую страницу. Единственное место, где мы просим человека о чём-то, вело в никуда.
+FBDIR="$(mktemp -d)"; FBPROJ="$(mktemp -d)"
+FB_OUT=$( cd "$FBPROJ" && git init -q . && HOME="$FBDIR" node "$CLI" init 2>&1 )
+if printf '%s' "$FB_OUT" | grep -qE 'https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+'; then
+  ok "просьба про звезду ведёт на репозиторий, а не на github.com/<имя пакета>"
+else
+  bad "ссылка на репозиторий собрана неверно" "$(printf '%s' "$FB_OUT" | grep -i github | head -2)"
+fi
+rm -rf "$FBDIR" "$FBPROJ"
+
+# --- 34. обязательная форма отчёта -------------------------------------------
+# ЗАЧЕМ. Первый чужой прогон дал отчёт «12 гейтов зелёные» — при том что все 12 стояли на
+# слабейшем рецепте, а половина методичек не была прочитана. Пересказ по памяти выбирает
+# удобное; отчёт обязан собираться прогоном.
+REPDIR="$(mktemp -d)"
+(
+  cd "$REPDIR" && git init -q . && mkdir -p src &&
+  printf 'def f():\n    print("debug")\n' > src/a.py &&
+  node "$CLI" start >/dev/null 2>&1
+)
+REP_OUT=$( cd "$REPDIR" && node "$CLI" report 2>&1 ); REP_CODE=$?
+if [ "$REP_CODE" -ne 0 ] && printf '%s' "$REP_OUT" | grep -q '❌ no-print-in-prod'; then
+  ok "report краснеет кодом возврата и называет упавший гейт"
+else
+  bad "report не отличает красное от зелёного" "код $REP_CODE"
+fi
+if [ -f "$REPDIR/.aqk/report.md" ] && grep -q '^## ' "$REPDIR/.aqk/report.md"; then
+  ok "report сохраняет .aqk/report.md"
+else
+  bad "report не сохранил файл отчёта" "$REPDIR/.aqk/report.md"
+fi
+# Путь к методичке ИЩЕТСЯ: baseline лежит в подпапке ai/, и жёстко вписанный путь уже соврал.
+if printf '%s' "$REP_OUT" | grep -q '📖 .aqk/docs/ai/project-baseline.md'; then
+  ok "report находит методичку в подпапке, а не пишет путь наизусть"
+else
+  bad "report не нашёл project-baseline.md" "$(printf '%s' "$REP_OUT" | grep -i baseline | head -1)"
+fi
+rm -rf "$REPDIR"
+
+# --- 35. note пишет в журнал ЭТОГО проекта, а не в чужой ---------------------
+# Команда требовала клон нашего репозитория и писала урок туда, игнорируя lessons: из
+# манифеста проекта. Найдено первым чужим прогоном: человек завёл журнал руками.
+NOTEDIR="$(mktemp -d)"; NOTEHOME="$(mktemp -d)"
+(
+  cd "$NOTEDIR" && git init -q . && git config user.email t@t && git config user.name t &&
+  node "$CLI" init >/dev/null 2>&1 &&
+  mkdir -p incidents &&
+  sed -i 's|^lessons: ""|lessons: incidents|' .aqk.yml &&
+  printf '**Вывод.** 🔧 завели проверку\n' | HOME="$NOTEHOME" AQK_HOME="" node "$CLI" note "шишка" >/dev/null 2>&1
+)
+if [ -f "$NOTEDIR/incidents/README.md" ] && grep -q 'шишка' "$NOTEDIR/incidents/README.md"; then
+  ok "note пишет в journal этого проекта — lessons: из манифеста"
+else
+  bad "note проигнорировал lessons: и ушёл искать чужой клон" "$NOTEDIR/incidents/README.md"
+fi
+rm -rf "$NOTEDIR" "$NOTEHOME"
+
+# --- 36. .aqkignore прячет принесённый извне код ------------------------------
+# ЗАЧЕМ. В чужом проекте референс, принесённый из другого репозитория, попадал в находки
+# всех сканирующих гейтов. Единственным лечением была правка КОПИИ _skip.sh в проекте —
+# то есть настройка правкой чужого файла, которую затрёт следующий `aqk add`.
+IGNDIR="$(mktemp -d)"
+mkdir -p "$IGNDIR/third-party/inner" "$IGNDIR/src"
+printf 'def f():\n    print("свой")\n' > "$IGNDIR/src/mine.py"
+printf 'def f():\n    print("чужой")\n' > "$IGNDIR/third-party/inner/theirs.py"
+OUT_BEFORE="$(bash "$ROOT/kit/gates/no-print-in-prod/check.sh" "$IGNDIR" 2>&1)"
+printf '# принесено из другого репозитория\nthird-party/\n' > "$IGNDIR/.aqkignore"
+OUT_AFTER="$(bash "$ROOT/kit/gates/no-print-in-prod/check.sh" "$IGNDIR" 2>&1)"
+if printf '%s' "$OUT_BEFORE" | grep -q 'theirs.py' &&
+   ! printf '%s' "$OUT_AFTER" | grep -q 'theirs.py' &&
+   printf '%s' "$OUT_AFTER" | grep -q 'mine.py'; then
+  ok ".aqkignore прячет чужой код и не трогает свой"
+else
+  bad ".aqkignore не работает" "до: $(printf '%s' "$OUT_BEFORE" | head -2) | после: $(printf '%s' "$OUT_AFTER" | head -2)"
+fi
+rm -rf "$IGNDIR"
+
 # --- итог -------------------------------------------------------------------
 printf '\n'
 if [ "$FAIL" -eq 0 ]; then

package/tool/selfcheck/units.mjs

@@ -12,7 +12,9 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { parseManifest, manifestWithGate } from "../lib/manifest.mjs";
-import { triggerVerdict, recipeFor, stems, overlap, EXT_LANG } from "../lib/repo.mjs";
+import { triggerVerdict, recipeFor, stems, overlap, EXT_LANG, whichSync } from "../lib/repo.mjs";
+import { CATALOGS, pickLang, L } from "../i18n/index.mjs";
+import { dirname } from "node:path";
 
 const facts = (over = {}) => ({ langs: new Set(), files: 0, ...over });
 
@@ -52,7 +54,8 @@ test("условия складываются по И: одно ложное с
 
 test("причина, по которой запись скрыта, называется словами", () => {
   const v = triggerVerdict({ trigger: { langs: "python, typescript" } }, facts({ langs: new Set(["go"]) }));
-  assert.match(v.why, /нет языков: python, typescript/);
+  // Сверяем с каталогом, а не с буквами: текст переводится, а выбор причины — нет.
+  assert.equal(v.why, L.trigger.noLangs("python, typescript"));
 });
 
 test("always: false значит «никогда не применимо», а не «условие пропущено»", () => {
@@ -64,7 +67,7 @@ test("неизвестное условие скрывает запись, а н
   // Молча пропустить незнакомое условие значит показать запись всем подряд.
   const v = triggerVerdict({ trigger: { has_kubernetes: "true" } }, facts());
   assert.equal(v.applies, false);
-  assert.match(v.why, /не умеет считать/);
+  assert.equal(v.why, L.trigger.unknown("has_kubernetes"));
 });
 
 // --- выбор рецепта ------------------------------------------------------------
@@ -74,7 +77,7 @@ test("без родного языка берётся переносимый р
 });
 
 test("рецепта нет — так и сказано, а не пустая строка", () => {
-  assert.equal(recipeFor({ slug: "x", recipes: {} }, facts()), "рецепт не описан");
+  assert.equal(recipeFor({ slug: "x", recipes: {} }, facts()), L.recipe.none);
 });
 
 // --- дедупликация по намерению ------------------------------------------------
@@ -101,5 +104,77 @@ test("гейт дописывается в блок gates и не дублиру
 test("без блока gates программа объясняет, чего не хватает", () => {
   const r = manifestWithGate("aqk: 1\n", "x", "bash y.sh");
   assert.equal(r.text, null);
-  assert.match(r.why, /нет блока gates/);
+  assert.equal(r.why, L.manifest.noGatesBlock);
+});
+
+// --- каталоги строк не расходятся ---------------------------------------------
+// ЗАЧЕМ. «Поддерживаем два языка» — утверждение, которое обязана держать машина, а не память
+// того, кто правил вывод в последний раз. Забытый ключ в одном каталоге даёт `undefined` в
+// выводе — не отказ, а тихую порчу текста ровно у того, кто пришёл на втором языке.
+// В массивы заходим тоже: ступени уровней и многострочные пояснения лежат массивами, и без
+// этого проверка сравнивала бы их как один непрозрачный «object» — то есть не сравнивала.
+// Заодно сверяется длина: пояснение из трёх строк на одном языке и из двух на другом — тоже
+// расхождение.
+function keyPaths(obj, prefix = "") {
+  const out = [];
+  for (const [k, v] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === "object") out.push(...keyPaths(v, path));
+    else out.push(`${path}:${typeof v}`);
+  }
+  return out.sort();
+}
+
+test("оба каталога строк несут одни и те же ключи одного типа", () => {
+  const a = keyPaths(CATALOGS.ru);
+  const b = keyPaths(CATALOGS.en);
+  const onlyRu = a.filter((k) => !b.includes(k));
+  const onlyEn = b.filter((k) => !a.includes(k));
+  assert.deepEqual(onlyRu, [], `есть только в ru: ${onlyRu.join(", ")}`);
+  assert.deepEqual(onlyEn, [], `есть только в en: ${onlyEn.join(", ")}`);
+  assert.ok(a.length > 0);
+});
+
+test("ни одна строка вывода не осталась пустой", () => {
+  for (const [lang, cat] of Object.entries(CATALOGS)) {
+    for (const path of keyPaths(cat)) {
+      const [key, kind] = path.split(":");
+      if (kind !== "string") continue;
+      const value = key.split(".").reduce((o, k) => o[k], cat);
+      assert.ok(value.trim().length > 0, `пустая строка ${lang}.${key}`);
+    }
+  }
+});
+
+test("язык берётся из AQK_LANG, потом из локали, иначе английский", () => {
+  assert.equal(pickLang({ AQK_LANG: "ru" }), "ru");
+  assert.equal(pickLang({ AQK_LANG: "en_US.UTF-8", LANG: "ru_RU.UTF-8" }), "en");
+  assert.equal(pickLang({ LANG: "ru_RU.UTF-8" }), "ru");
+  assert.equal(pickLang({ LC_ALL: "ru_RU.UTF-8", LANG: "en_US.UTF-8" }), "ru");
+  assert.equal(pickLang({ LANG: "de_DE.UTF-8" }), "en");
+  assert.equal(pickLang({}), "en");
+});
+
+// --- поиск программы в PATH ---------------------------------------------------
+// ЗАЧЕМ. Раньше наличие программы проверялось через `command -v` в оболочке. На Windows
+// оболочка — cmd.exe, где такой команды нет, и ответ был «не установлено» ДЛЯ ЛЮБОЙ
+// программы: родной рецепт становился недостижим, гейт молча вставал на слабейший
+// переносимый вариант, а прогон показывал зелёное. Нашлось на чужом прогоне, не у нас.
+test("программа в PATH находится, несуществующая — нет", () => {
+  assert.ok(whichSync("node"), "node обязан находиться: им же запущена эта проверка");
+  assert.equal(whichSync("нет-такой-программы-12345"), null);
+  assert.equal(whichSync(""), null);
+});
+
+test("поиск не зависит от оболочки — работает с пустым окружением", () => {
+  // Тот самый случай: оболочки нет или она другая. Ответ обязан быть «не нашли»,
+  // а не исключение и не ложное «нашли».
+  assert.equal(whichSync("node", { PATH: "" }), null);
+  const dir = dirname(process.execPath);
+  assert.ok(whichSync(process.platform === "win32" ? "node" : "node", { PATH: dir }));
+});
+
+test("команда путём, а не именем, ищется на диске, а не в PATH", () => {
+  assert.ok(whichSync(process.execPath));
+  assert.equal(whichSync("./нет-такого-файла.sh"), null);
 });