agent-quality-kit 0.2.5 → 0.3.0

package/README.md

@@ -104,6 +104,23 @@ let it grow. The rule applies from the day it is installed — the old code stay
 via `npx` the package is temporary, and tomorrow the command in your manifest would point at
 nothing.
 
+## Third-party code inside the repository
+
+A reference copy, vendored code, generated clients — code that lives here but was not written
+here. The scanning checks will skip it if you add `.aqkignore` in the root: one pattern per line,
+`#` starts a comment, and `*` does not cross `/`.
+
+```
+# brought in from another repository
+third-party/
+vendor/
+*.generated.js
+```
+
+`aqk report` prints the contents of this file as its own section. Hiding things silently is the
+same class as a silent gate: a line here means there is no protection along that path, and will
+not be.
+
 ## The catalogue of promises
 
 `doctor` inspects the repository — languages, existing gates — and shows **only what applies**:

package/README.ru.md

@@ -101,6 +101,22 @@ aqk why "файл вырос до девяти тысяч строк"
 `add` **копирует проверку в репозиторий**, а не ссылается на пакет: при установке через `npx`
 пакет временный, и завтра команда в манифесте указывала бы в никуда.
 
+## Чужой код в репозитории
+
+Референс, вендоринг, сгенерированные клиенты — код лежит здесь, но написан не здесь. Сканирующие
+проверки по нему не пойдут, если завести `.aqkignore` в корне: по шаблону на строку, `#` —
+комментарий, звёздочка не переходит через `/`.
+
+```
+# принесено из другого репозитория
+third-party/
+vendor/
+*.generated.js
+```
+
+`aqk report` печатает содержимое этого файла отдельным разделом. Скрытое молча — тот же класс,
+что молчащий гейт: строка здесь означает, что защиты по этому пути нет и не будет.
+
 ## Каталог обещаний
 
 `doctor` смотрит на репозиторий — языки, наличие гейтов — и показывает **только применимое**:

package/kit/gates/_skip.sh

@@ -21,11 +21,39 @@ migrations"
 # (red-team тесты, что угодно) становился невидим для secrets-not-in-code во всех проектах,
 # куда ставили гейт. Фильтр ниже смотрит на путь целиком: только `gates/<имя>/red|green/`,
 # а не голое имя каталога.
+# Список исключений САМОГО ПРОЕКТА: файл .aqkignore в корне, по шаблону на строку, «#» —
+# комментарий. Нужен для кода, который лежит в репозитории, но написан не здесь: референс,
+# вендоринг, сгенерированные клиенты. Без него единственным способом настройки была правка
+# КОПИИ этого файла в проекте — то есть настройка правкой чужого файла, которую затирает
+# следующий `aqk add`. Найдено первым чужим прогоном.
+#
+# Шаблон — фрагмент пути: `vendor/`, `apps/legacy`, `*.generated.js`. Звёздочка не переходит
+# через «/», как в .gitignore, — иначе «src/*» прятало бы весь проект.
+aqkignore_re() {
+  F="${1:-.}/.aqkignore"
+  [ -f "$F" ] || return 1
+  sed -e 's/#.*$//' -e 's|/*[[:space:]]*$||' -e 's/^[[:space:]]*//' "$F" |
+    grep -v '^$' |
+    sed -e 's/[][(){}.^$+?|\\]/\\&/g' -e 's/\*/[^\/]*/g' |
+    tr '\n' '|' | sed 's/|$//'
+}
+
+# Один фильтр на два дела, и это осознанно: его зовут все семь сканирующих проверок, а их
+# копии уже лежат в чужих проектах. Добавить сюда — значит, что обновление комплекта включает
+# .aqkignore и у тех, кто ставил гейты раньше, без перекопирования их check.sh.
 own_samples_filter() {
-  case "${1:-}" in
-    */red|*/red/|*/green|*/green/) cat ;;
-    *) grep -vE '/gates/[^/]+/(red|green)(/|$)' ;;
+  DIR0="${1:-}"
+  RE="$(aqkignore_re "$DIR0")"
+  case "$DIR0" in
+    # Цель проверки — сам образец: тогда прятать его нельзя, иначе гейт «пройдёт» на красном.
+    */red|*/red/|*/green|*/green/) SAMPLES="cat" ;;
+    *) SAMPLES="grep -vE /gates/[^/]+/(red|green)(/|\$)" ;;
   esac
+  if [ -n "$RE" ]; then
+    $SAMPLES | grep -vE "(^|/)($RE)(/|:|\$)"
+  else
+    $SAMPLES
+  fi
 }
 
 # Расширения, где `print` и маркеры долга — конструкции языка, а не текст. Проверять по ним

package/kit/gates/commit-explains-itself/gate.yml

@@ -1,4 +1,5 @@
 intent: коммит несёт мини-отчёт — что сделано и в чём агент не уверен
+intent_en: the commit carries a mini-report — what was done and what the agent is unsure about
 
 trigger:
   always: true

package/kit/gates/complexity-limit/gate.yml

@@ -1,4 +1,5 @@
 intent: функция не вырастает до сложности, в которой её нельзя удержать в голове
+intent_en: a function does not grow past the complexity you can hold in your head
 
 trigger:
   always: true

package/kit/gates/dead-code/gate.yml

@@ -1,4 +1,5 @@
 intent: код, который никто не вызывает, не остаётся в проекте
+intent_en: code nobody calls does not stay in the project
 
 # Только там, где есть готовый инструмент: переносимой проверки здесь быть не может, а
 # показывать запись тем, кому её нечем исполнить, — значит показывать работу, которую

package/kit/gates/deps-are-pinned/gate.yml

@@ -1,4 +1,5 @@
 intent: версии зависимостей закреплены — сборка воспроизводима
+intent_en: dependency versions are pinned — the build is reproducible
 
 trigger:
   has_deps: true

package/kit/gates/duplicate-code/gate.yml

@@ -1,4 +1,5 @@
 intent: один и тот же код не размножается по проекту копиями
+intent_en: the same code does not multiply into copies across the project
 
 trigger:
   files_gt: 20

package/kit/gates/entry-links-exist/gate.yml

@@ -2,6 +2,7 @@
 # Читается программой; всё, что нельзя выполнить, живёт в README.md рядом.
 
 intent: файлы, на которые ссылается точка входа, существуют на диске
+intent_en: files the entry point links to actually exist on disk
 
 # Когда запись показывается человеку. Отсутствие триггера сделало бы её шумом
 # для тех, кого она не касается.

package/kit/gates/file-size-limit/gate.yml

@@ -1,4 +1,5 @@
 intent: файл не вырастает до размера, в котором агент теряется
+intent_en: a file does not grow to a size where the agent gets lost
 
 trigger:
   always: true

package/kit/gates/gate-has-samples/gate.yml

@@ -1,4 +1,5 @@
 intent: у каждого объявленного гейта есть красный и зелёный образец
+intent_en: every declared gate has a red and a green sample
 
 trigger:
   has_gates: true

package/kit/gates/gates-are-runnable/gate.yml

@@ -1,4 +1,5 @@
 intent: каждый гейт, объявленный в манифесте, существует и запускается
+intent_en: every gate declared in the manifest exists and runs
 
 trigger:
   has_gates: true

package/kit/gates/gates-run-in-ci/gate.yml

@@ -1,4 +1,5 @@
 intent: каждый объявленный гейт запускается конвейером, а не только руками
+intent_en: every declared gate runs in the pipeline, not only by hand
 
 # Условия складываются: запись касается только тех, у кого есть и гейты, и конвейер.
 # Нет конвейера — сначала он, а не эта проверка.

package/kit/gates/lesson-has-outcome/gate.yml

@@ -1,4 +1,5 @@
 intent: каждая записанная шишка кончается решением, а не рассказом
+intent_en: every recorded bruise ends in a decision, not a story
 
 # Проверять нечего там, где журнала нет: запись сама скажет об этом и промолчит.
 trigger:

package/kit/gates/no-print-in-prod/check.sh

@@ -14,7 +14,9 @@ DIR="${1:-.}"
 #
 # На настоящем проекте без этого различия 285 находок из 330 пришли из scripts/ и оснастки.
 # Гейт, который на 86% состоит из ложных сработок, выключают целиком.
-TOOLING="--exclude-dir=scripts --exclude-dir=tools --exclude-dir=bin --exclude-dir=examples --exclude-dir=notebooks --exclude-dir=docs --exclude-dir=.claude --exclude-dir=gates --exclude-dir=gates-reference"
+TOOLING="--exclude-dir=scripts --exclude-dir=tools --exclude-dir=bin --exclude-dir=examples --exclude-dir=notebooks --exclude-dir=docs --exclude-dir=.claude --exclude-dir=gates"
+# `gates-reference` отсюда убран: это имя каталога ОДНОГО проекта, зашитое в общий
+# инструмент. Такому место в .aqkignore самого проекта — он появился позже этой строки.
 
 # Проект называет СВОИ каталоги, где печать — интерфейс, а не отладка: у программы командной
 # строки это её исходники целиком. Объявляется в манифесте, рядом с командой, и потому видно

package/kit/gates/no-print-in-prod/gate.yml

@@ -1,4 +1,5 @@
 intent: отладочная печать не доезжает до прод-кода
+intent_en: debug printing does not reach production code
 
 # Запись касается только языков, где есть эта конструкция. В проекте на Go или
 # Rust она не показывается вовсе.

package/kit/gates/secrets-not-in-code/gate.yml

@@ -1,4 +1,5 @@
 intent: ключи, пароли и приватные ключи не попадают в код
+intent_en: keys, passwords and private keys do not end up in the code
 
 trigger:
   always: true

package/kit/gates/swallowed-error/gate.yml

@@ -1,4 +1,5 @@
 intent: ошибка не глушится молча — она обработана и записана либо проброшена
+intent_en: an error is not silently swallowed — it is handled and logged, or re-raised
 
 trigger:
   always: true

package/kit/gates/todo-without-task/gate.yml

@@ -1,4 +1,5 @@
 intent: маркеров «доделать потом» нет в готовом коде — вместо них заведённая задача
+intent_en: "fix later" markers are absent from finished code — a filed task replaces them
 
 trigger:
   always: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-kit",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "AQK — Agent Quality Kit: переносимый комплект, приводящий проект в состояние, пригодное для работы агентов. Правила, механические упоры, накопленные уроки. Одна команда, любой инструмент.",
   "type": "module",
   "bin": {

package/tool/commands/doctor.mjs

@@ -6,6 +6,7 @@ import { spawnSync } from "node:child_process";
 import { CWD, PKG_ROOT, TARGET_DIR, SELF, c, exists } from "../lib/core.mjs";
 import { readManifest, assessLevel } from "../lib/manifest.mjs";
 import { detectFacts, readCatalog, triggerVerdict, recipeFor } from "../lib/repo.mjs";
+import { L } from "../i18n/index.mjs";
 
 async function reportCatalog(man, facts) {
   const catalog = await readCatalog();
@@ -19,27 +20,27 @@ async function reportCatalog(man, facts) {
     else todo.push(rec);
   }
 
-  console.log(c.bold(`\n  Гейты\n`));
+  console.log(c.bold(`\n  ${L.doctor.gatesHeading}\n`));
   const marks = ["has_ci", "has_db", "has_docker", "has_tests", "has_deps"]
     .filter((k) => facts[k])
     .map((k) => k.replace("has_", ""));
   console.log(
-    c.dim(`  языки: ${[...facts.langs].join(", ") || "не определены"} · файлов: ${facts.files}` +
-      (marks.length ? ` · есть: ${marks.join(", ")}` : "") + "\n")
+    c.dim(`  ${L.doctor.langs}: ${[...facts.langs].join(", ") || L.doctor.langsUnknown} · ${L.doctor.files}: ${facts.files}` +
+      (marks.length ? ` · ${L.doctor.hasThings}: ${marks.join(", ")}` : "") + "\n")
   );
 
   for (const rec of held) console.log(`  ${c.green("✔")}  ${rec.slug.padEnd(22)} ${c.dim(rec.intent || "")}`);
   for (const rec of todo) {
     console.log(`  ${c.yellow("✘")}  ${rec.slug.padEnd(22)} ${rec.intent || ""}`);
-    console.log(c.dim(`      поставить: ${SELF} add ${rec.slug}`));
+    console.log(c.dim(`      ${L.doctor.install(`${SELF} add ${rec.slug}`)}`));
   }
   if (skip.length) {
-    console.log(c.dim(`\n  Не применимо к этому репозиторию (${skip.length}):`));
+    console.log(c.dim(`\n  ${L.doctor.notApplicable(skip.length)}`));
     for (const [rec, why] of skip) console.log(c.dim(`  ·  ${rec.slug.padEnd(22)} ${why}`));
   }
   console.log(
-    `\n  ${c.bold("Итого:")} держит машина ${held.length}, применимо но не поставлено ${c.yellow(todo.length)}, ` +
-      c.dim(`скрыто ${skip.length}`) + "\n"
+    `\n  ${c.bold(L.doctor.total)} ${L.doctor.totalHeld(held.length)}, ${L.doctor.totalTodo(c.yellow(todo.length))}, ` +
+      c.dim(L.doctor.totalSkip(skip.length)) + "\n"
   );
 }
 
@@ -61,7 +62,7 @@ function runGates(man) {
   const gates = declaredGates(man);
   if (!gates.length) return { failed: 0, ran: 0, results: [] };
 
-  console.log(c.bold("\n  Прогон объявленных гейтов\n"));
+  console.log(c.bold(`\n  ${L.doctor.runHeading}\n`));
   let failed = 0;
   const results = [];
 
@@ -71,9 +72,9 @@ function runGates(man) {
     const secs = (Math.max(0, Date.now() - t0) / 1000).toFixed(1);
 
     if (r.error && r.error.code === "ETIMEDOUT") {
-      console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red("не уложился в 5 минут")}`);
+      console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.timeout)}`);
       failed++;
-      results.push({ name, cmd, ok: false, secs, note: "не уложился в 5 минут" });
+      results.push({ name, cmd, ok: false, secs, note: L.doctor.timeout });
       continue;
     }
     const code = r.status;
@@ -83,9 +84,9 @@ function runGates(man) {
     } else {
       failed++;
       const out = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").filter(Boolean);
-      console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(`код ${code}`)} ${c.dim(`· ${secs}s · ${cmd}`)}`);
+      console.log(`  ${c.red("✘")}  ${name.padEnd(14)} ${c.red(L.doctor.exitCode(code))} ${c.dim(`· ${secs}s · ${cmd}`)}`);
       for (const line of out.slice(0, 3)) console.log(c.dim(`        ${line.slice(0, 100)}`));
-      if (out.length > 3) console.log(c.dim(`        … и ещё ${out.length - 3} строк`));
+      if (out.length > 3) console.log(c.dim(`        ${L.doctor.moreLines(out.length - 3)}`));
       results.push({ name, cmd, ok: false, secs, code });
     }
   }
@@ -100,13 +101,13 @@ async function writeRunReport({ version, reached, results }) {
   const stamp = new Date().toISOString().replace("T", " ").slice(0, 16);
   const ok = results.filter((r) => r.ok).length;
   const lines = [
-    `# aqk doctor --run — ${stamp}`,
-    version ? `версия: ${version}` : null,
-    `уровень: AQK-${reached < 0 ? "нет" : reached}`,
+    `# ${L.report.title} — ${stamp}`,
+    version ? `${L.report.version}: ${version}` : null,
+    `${L.report.level}: AQK-${reached < 0 ? L.doctor.levelNone : reached}`,
     "",
-    ...results.map((r) => `${r.ok ? "✔" : "✘"} ${r.name} — ${r.secs}s${r.ok ? "" : ` (${r.note || `код ${r.code}`})`}`),
+    ...results.map((r) => `${r.ok ? "✔" : "✘"} ${r.name} — ${r.secs}s${r.ok ? "" : ` (${r.note || L.doctor.exitCode(r.code)})`}`),
     "",
-    `итого: ${ok} из ${results.length} зелёных`,
+    L.report.summary(ok, results.length),
   ].filter((l) => l !== null);
 
   const dst = join(CWD, TARGET_DIR, "last-run.md");
@@ -129,11 +130,11 @@ async function cmdDoctor() {
   // репозитории и требовал разложить комплект в комплект.
   const inKit = resolve(CWD) === resolve(PKG_ROOT);
   const checks = [
-    inKit ? ["kit/docs", "методички — здесь оригиналы, а не копия"] : [".aqk/docs", "методички"],
-    inKit ? ["kit/rules", "стандарты — здесь оригиналы, а не копия"] : [".aqk/rules", "стандарты"],
-    ["AGENTS.md", "точка входа для агентов"],
-    [".gitignore", "гигиена репозитория"],
-    [".git", "проект под контролем версий"],
+    inKit ? ["kit/docs", L.doctor.docsKit] : [".aqk/docs", L.doctor.docs],
+    inKit ? ["kit/rules", L.doctor.rulesKit] : [".aqk/rules", L.doctor.rules],
+    ["AGENTS.md", L.doctor.agents],
+    [".gitignore", L.doctor.gitignore],
+    [".git", L.doctor.git],
   ];
 
   let missing = 0;
@@ -150,8 +151,8 @@ async function cmdDoctor() {
     const emptyCommands = (text.match(/^- [^:]+: ``$/gm) || []).length;
     if (emptyCommands) {
       console.log(
-        `\n  ${c.yellow("!")}  В AGENTS.md ${emptyCommands} незаполненных команд. ` +
-          c.dim("Агент не может выполнить пустую строку.")
+        `\n  ${c.yellow("!")}  ${L.doctor.emptyCommands(emptyCommands)} ` +
+          c.dim(L.doctor.emptyCommandsWhy)
       );
     }
   }
@@ -159,7 +160,7 @@ async function cmdDoctor() {
   const man = await readManifest();
   const { reached, steps } = await assessLevel(man);
 
-  console.log(c.bold("\n  Уровень соответствия AQK\n"));
+  console.log(c.bold(`\n  ${L.doctor.levelHeading}\n`));
   for (const s of steps) {
     const mark = s.ok ? c.green("✔") : reached + 1 === s.level ? c.yellow("→") : c.dim("·");
     console.log(`  ${mark}  AQK-${s.level}  ${s.title}`);
@@ -171,25 +172,21 @@ async function cmdDoctor() {
   // работающих проверок и без манифеста стоит на нуле — и это сообщение обязано это объяснить,
   // иначе человек услышит «у тебя плохо» и закроет.
   if (reached < 0 && !man) {
-    console.log(c.yellow("\n  Уровень: стандарт в этом репозитории не заведён.\n"));
-    console.log(
-      c.dim("  Это не оценка проекта. Уровень мерит не зрелость практики, а то, можно ли\n") +
-      c.dim("  прочитать её машиной. Проверки могут стоять и работать — но пока они не\n") +
-      c.dim("  объявлены в .aqk.yml, ни агент, ни конвейер, ни новый человек о них не знают.\n")
-    );
+    console.log(c.yellow(`\n  ${L.doctor.levelNotSet}\n`));
+    console.log(L.doctor.levelNotSetWhy.map((line) => c.dim(`  ${line}`)).join("\n") + "\n");
   } else {
     console.log(
       reached < 0
-        ? c.yellow(`\n  Уровень: манифест есть, но AQK-0 не пройден.\n`)
-        : c.green(`\n  Уровень: AQK-${reached}.\n`)
+        ? c.yellow(`\n  ${L.doctor.levelManifestNoZero}\n`)
+        : c.green(`\n  ${L.doctor.level(reached)}\n`)
     );
   }
 
   if (next) {
-    console.log(`  ${c.bold(`Чтобы достичь AQK-${next.level}:`)} ${next.need}`);
-    console.log(c.dim(`  Что это даст: ${next.gives}\n`));
+    console.log(`  ${c.bold(L.doctor.toReach(next.level))} ${next.need}`);
+    console.log(c.dim(`  ${L.doctor.gives(next.gives)}\n`));
   } else {
-    console.log(c.green("  Все ступени пройдены.\n"));
+    console.log(c.green(`  ${L.doctor.allDone}\n`));
   }
 
   const facts = await detectFacts(man);
@@ -205,8 +202,8 @@ async function cmdDoctor() {
     await writeRunReport({ version, reached, results: run.results });
   } else if (gates.length) {
     console.log(
-      c.yellow(`  ${gates.length} гейтов объявлено, но не запускалось.`) +
-        c.dim(` «Объявлен» и «работает» — разные утверждения: ${SELF} doctor --run\n`)
+      c.yellow(`  ${L.doctor.declaredNotRun(gates.length)}`) +
+        c.dim(L.doctor.declaredNotRunWhy(`${SELF} doctor --run`) + "\n")
     );
   }
 
@@ -217,8 +214,8 @@ async function cmdDoctor() {
     const pass = reached >= min && gateFailed === 0;
     console.log(
       pass
-        ? c.green(`  Порог AQK-${min} пройден.\n`)
-        : c.red(`  Порог AQK-${min} НЕ пройден: сейчас AQK-${reached < 0 ? "нет" : reached}.\n`)
+        ? c.green(`  ${L.doctor.thresholdPass(min)}\n`)
+        : c.red(`  ${L.doctor.thresholdFail(min, reached < 0 ? L.doctor.levelNone : reached)}\n`)
     );
     process.exit(pass ? 0 : 1);
   }
@@ -227,4 +224,4 @@ async function cmdDoctor() {
 
 // Наружу — только команда. Остальное здесь же и используется: экспорт, который никто не
 // импортирует, читается как «это часть договора» и мешает менять внутренности.
-export { cmdDoctor };
+export { cmdDoctor, runGates, declaredGates };