agent-quality-kit 0.6.0 → 0.7.0

package/tool/selfcheck/units.mjs

@@ -11,9 +11,9 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { parseManifest, manifestWithGate, unknownKeys, entryLifecycle } from "../lib/manifest.mjs";
+import { parseManifest, manifestWithGate, unknownKeys, entryLifecycle, advisorySet, KNOWN_KEYS } from "../lib/manifest.mjs";
 import { triggerVerdict, recipeFor, stems, overlap, EXT_LANG, whichSync } from "../lib/repo.mjs";
-import { scopeOutput } from "../lib/scope.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";
 import { badgeMarkdown, BADGE_RE, placesToCheck } from "../commands/badge.mjs";
@@ -358,3 +358,114 @@ test("сужение по дифу: гейт без путей в выводе
   assert.equal(r.scopable, false);
   assert.equal(scopeOutput(["src/old.py:1: печать"], new Set(["src/new.py"])).scopable, true);
 });
+
+
+// --- совет по починке не теряется в обрезке ----------------------------------
+// ЗАЧЕМ. Все девятнадцать записей каталога печатают строку «почини: …» последней. `doctor --run`
+// показывает три первые строки вывода и обрезает остальное — то есть ровно ту строку, ради
+// которой человек и смотрит на красное, он не видит никогда. Находка без действия — это повод
+// закрыть окно, а не починить.
+test("совет по починке отделяется от находок и не обрезается", () => {
+  const out = [
+    "src/a.py:3: печать",
+    "src/b.py:9: печать",
+    "src/c.py:1: печать",
+    "src/d.py:7: печать",
+    "  почини: замени на вызов системы логов",
+    "  тогда запись попадёт в общий журнал",
+  ];
+  const r = splitAdvice(out);
+  assert.equal(r.findings.length, 4);
+  assert.equal(r.advice.length, 2);
+  // Продолжение совета едет вместе с ним: без второй строки первая обрывается на полуслове.
+  assert.equal(r.advice[1].includes("общий журнал"), true);
+});
+
+test("совет по починке опознаётся на обоих языках", () => {
+  assert.equal(splitAdvice(["a.py:1: x", "  fix: replace with a logger call"]).advice.length, 1);
+  assert.equal(splitAdvice(["a.py:1: x", "  почини: замени на логгер"]).advice.length, 1);
+});
+
+// Вывод без совета — это не ошибка разбора, а признак записи, которая не говорит, что делать.
+// Разбор обязан вернуть пустой совет, а не выдумать его из последней строки.
+test("вывод без совета не превращается в совет", () => {
+  const r = splitAdvice(["src/a.py:3: печать", "src/b.py:9: печать"]);
+  assert.equal(r.advice.length, 0);
+  assert.equal(r.findings.length, 2);
+});
+
+
+// Совет бывает не только в конце: `deps-are-pinned` печатает его внутри вспомогательной
+// функции, вызываемой шесть раз, и находки идут ПОСЛЕ. Пока советом считалось «всё от первой
+// метки до конца», сорок находок уезжали в жёлтый список без обрезки — ровно та стена красного,
+// против которой написан этот модуль. Найдено ревью 2026-09-06.
+test("совет, вставленный посреди вывода, не проглатывает находки", () => {
+  const r = splitAdvice([
+    "  почини: закрепи версии",
+    "src/a.py:1: x",
+    "src/b.py:2: x",
+    "src/c.py:3: x",
+    "  почини: и вот это тоже",
+    "    вторая строка совета",
+  ]);
+  assert.equal(r.findings.length, 3);
+  assert.equal(r.advice.length, 3);
+});
+
+// Продолжение совета не должно съедать находку, стоящую сразу за ним.
+test("находка сразу после совета остаётся находкой", () => {
+  const r = splitAdvice(["  почини: сделай так", "    пояснение", "src/z.py:9: x"]);
+  assert.equal(r.findings.length, 1);
+  assert.equal(r.findings[0].includes("src/z.py"), true);
+});
+
+
+// --- правило, введённое совещательным ----------------------------------------
+// ЗАЧЕМ. Правило вводят в проект, где старый код ему не соответствует. Храповик отвечает на
+// это одним способом: старое становится долгом. Второй способ — показывать, не роняя, пока
+// команда договаривается. Сегодня его нет вовсе: находка либо роняет сборку, либо не существует.
+//
+// ПОЧЕМУ ОБЪЯВЛЕНИЕМ, А НЕ ФЛАГОМ ПРОГОНА. Флаг «не роняй ничего» — это `continue-on-error`,
+// против которого написана наша же запись ci-actually-fails: он понижает всё разом, не виден
+// в дифе и не назван в сводке. Список в манифесте виден, именуется и считается всегда.
+test("совещательные гейты читаются из манифеста списком", () => {
+  const man = parseManifest("aqk: 1\nadvisory:\n  - complexity-limit\n  - duplicate-code\n");
+  const a = advisorySet(man);
+  assert.equal(a.has("complexity-limit"), true);
+  assert.equal(a.has("duplicate-code"), true);
+  assert.equal(a.has("secrets-not-in-code"), false);
+});
+
+test("список в одну строку читается так же", () => {
+  const a = advisorySet(parseManifest("advisory: [complexity-limit, duplicate-code]\n"));
+  assert.equal(a.size, 2);
+});
+
+// Отсутствие блока — это ноль совещательных, а не «все совещательные».
+test("без блока advisory совещательных нет", () => {
+  assert.equal(advisorySet(parseManifest("aqk: 1\n")).size, 0);
+  assert.equal(advisorySet(null).size, 0);
+});
+
+// Поле обязано быть известным манифесту: иначе опечатка «advisery:» молча означала бы
+// «совещательных нет», и правило, которое человек считал введённым, роняло бы сборку.
+test("advisory — известное поле манифеста", () => {
+  assert.equal(KNOWN_KEYS.includes("advisory"), true);
+  assert.deepEqual(unknownKeys({ aqk: 1, advisory: [] }), []);
+});
+
+
+// --- правила на языке проекта ------------------------------------------------
+// ЗАЧЕМ. Русский текст правил в англоязычном проекте — это первое, что там откроет человек,
+// и первое, чего он не прочитает. Русская версия остаётся источником истины, английская —
+// переводом. Совпадение содержания машина не сторожит, а вот НАБОР ФАЙЛОВ обязана: добавили
+// правило на одном языке и забыли про другой — половина мира получит комплект без него.
+test("наборы файлов правил совпадают на обоих языках", async () => {
+  const { readdir } = await import("node:fs/promises");
+  const { fileURLToPath } = await import("node:url");
+  const at = (d) => fileURLToPath(new URL(`../../kit/${d}`, import.meta.url));
+  const ru = (await readdir(at("rules"))).filter((f) => f.endsWith(".md")).sort();
+  const en = (await readdir(at("rules-en"))).filter((f) => f.endsWith(".md")).sort();
+  assert.deepEqual(en, ru);
+  assert.equal(ru.length > 0, true);
+});

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

@@ -1,38 +0,0 @@
-#!/usr/bin/env sh
-# Отладочная печать переживает задачу и уезжает в прод: она не ошибка сборки и
-# не видна в ревью диффа на 400 строк. В проде это либо шум, либо утечка данных
-# мимо системы логов.
-DIR="${1:-.}"
-. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
-# Красный образец — намеренно сломанный код в репозитории. Сканирующий гейт обязан его
-# пропускать, иначе будет вечно краснеть на том, что сам же и положил. Исключение снимается,
-# когда проверяют сам образец: тогда каталог red и есть цель проверки.
-
-# Где печать законна и дефектом не является: вспомогательные скрипты, оснастка, примеры,
-# записные книжки. Это НЕ общий список исключений: секрет в scripts/ — такой же секрет,
-# а печать там — обычный способ говорить с человеком.
-#
-# На настоящем проекте без этого различия 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"
-# `gates-reference` отсюда убран: это имя каталога ОДНОГО проекта, зашитое в общий
-# инструмент. Такому место в .aqkignore самого проекта — он появился позже этой строки.
-
-# Проект называет СВОИ каталоги, где печать — интерфейс, а не отладка: у программы командной
-# строки это её исходники целиком. Объявляется в манифесте, рядом с командой, и потому видно
-# глазами: AQK_PRINT_OK_DIRS="tool cli" bash .../check.sh .
-#
-# ЗАЧЕМ ОТДЕЛЬНО ОТ ХРАПОВИКА. Сначала такие места записали долгом — и каждая новая строка
-# вывода красила проверку, требуя переснять реестр. Но долг — это то, что собираются погасить;
-# печать из программы командной строки убирать никто не будет. Долг, который нельзя погасить
-# работой, — не долг, а неверная мера: журнал, 2026-09-03.
-for D in ${AQK_PRINT_OK_DIRS:-}; do
-  TOOLING="$TOOLING --exclude-dir=$D"
-done
-HITS=$(grep -rnE $(skip_grep "$DIR") $(include_code) $TOOLING '(^|[^A-Za-z_.])(print\(|console\.log\(|fmt\.Print|println!|print!|dbg!|System\.out\.print|Console\.Write)' "$DIR" 2>/dev/null | drop_comments | own_samples_filter "$DIR")
-if [ -n "$HITS" ]; then
-  echo "$HITS"
-  echo "  почини: замени на вызов системы логов — тогда запись попадёт в общий журнал и уровень можно приглушить."
-  exit 1
-fi
-exit 0

package/kit/gates/no-print-in-prod/green/docs.ts

@@ -1,15 +0,0 @@
-// Печать внутри комментария — не печать. Пример в документации к функции и закомментированная
-// строка отладки одинаково не выполняются: находка здесь означает, что проверка читает текст,
-// а не код. Найдено прогоном по audit_project — семь находок из JSDoc и закомментированных строк.
-
-/**
- * Скачивает файл.
- *
- * @example
- *   const result = await download(id);
- *   console.log('Done:', result.file_url);
- */
-export async function download(id: string): Promise<string> {
-  // console.log('отладка', id);
-  return `/files/${id}`;
-}

package/kit/gates/no-print-in-prod/green/main.go

@@ -1,8 +0,0 @@
-package main
-
-import "log/slog"
-
-func handle(x int) int {
-	slog.Debug("got", "x", x)
-	return x + 1
-}

package/kit/gates/no-print-in-prod/green/main.rs

@@ -1,4 +0,0 @@
-fn handle(x: i32) -> i32 {
-    log::debug!("got {}", x);
-    x + 1
-}

package/kit/gates/no-print-in-prod/red/main.go

@@ -1,8 +0,0 @@
-package main
-
-import "fmt"
-
-func handle(x int) int {
-	fmt.Println("got", x)
-	return x + 1
-}

package/kit/gates/no-print-in-prod/red/main.rs

@@ -1,4 +0,0 @@
-fn handle(x: i32) -> i32 {
-    println!("got {}", x);
-    x + 1
-}

package/kit/gates/swallowed-error/check.sh

@@ -1,54 +0,0 @@
-#!/usr/bin/env sh
-# Тихо проглоченная ошибка — отказ, о котором никто не узнал. Система продолжает работать
-# «как будто всё хорошо», а причина всплывает через недели и в другом месте.
-DIR="${1:-.}"
-. "$(dirname "$0")/../_skip.sh" 2>/dev/null || SKIP_NAMES=".git .aqk node_modules .venv"
-
-# Список файлов собираем заранее. awk без файловых аргументов читает поток ввода и ждёт его
-# вечно: на проекте без файлов этих языков проверка зависала навсегда — в конвейере и в хуке
-# коммита, где поток ввода открыт. Найдено прогоном по проекту на Go.
-FILES=$(find "$DIR" $(skip_find "$DIR") -type f -print 2>/dev/null | only_code | own_samples_filter "$DIR")
-[ -z "$FILES" ] && exit 0
-
-printf '%s\n' "$FILES" | xargs -r awk '
-  FILENAME ~ /\/(\.git|\.aqk|node_modules|dist|build|vendor)\// { next }
-
-  # python: except ...: с пустым телом
-  prev ~ /^[[:space:]]*except([[:space:]]|:)/ && $0 ~ /^[[:space:]]*(pass|\.\.\.)[[:space:]]*$/ {
-    print FILENAME ":" FNR ": перехват без обработки — " gensub(/^[[:space:]]+/, "", 1, prev)
-  }
-  # python в одну строку
-  /^[[:space:]]*except[^:]*:[[:space:]]*(pass|\.\.\.)[[:space:]]*$/ {
-    print FILENAME ":" FNR ": перехват без обработки — " gensub(/^[[:space:]]+/, "", 1, $0)
-  }
-  # js/java/go-подобные: catch (...) { } пустой
-  /catch[[:space:]]*(\([^)]*\))?[[:space:]]*\{[[:space:]]*\}/ {
-    print FILENAME ":" FNR ": перехват без обработки — " gensub(/^[[:space:]]+/, "", 1, $0)
-  }
-  # go: пустое тело после проверки ошибки, либо ошибка присвоена в пустоту
-  prev ~ /if[[:space:]]+err[[:space:]]*!=[[:space:]]*nil/ && $0 ~ /^[[:space:]]*\}[[:space:]]*$/ {
-    print FILENAME ":" FNR ": ошибка проверена и выброшена — " gensub(/^[[:space:]]+/, "", 1, prev)
-  }
-  /^[[:space:]]*_[[:space:]]*=[[:space:]]*err[[:space:]]*$/ {
-    print FILENAME ":" FNR ": ошибка присвоена в пустоту — " gensub(/^[[:space:]]+/, "", 1, $0)
-  }
-  # rust: результат отброшен без разбора
-  /\.ok\(\);[[:space:]]*$/ || /let[[:space:]]+_[[:space:]]*=[^;]*\?[[:space:]]*;/ {
-    print FILENAME ":" FNR ": результат отброшен без разбора — " gensub(/^[[:space:]]+/, "", 1, $0)
-  }
-  # обещания: .catch(() => {})
-  /\.catch\([^)]*=>[[:space:]]*\{[[:space:]]*\}\)/ {
-    print FILENAME ":" FNR ": перехват без обработки — " gensub(/^[[:space:]]+/, "", 1, $0)
-  }
-  { prev = $0 }
-' > /tmp/.swallowed.$$ 2>/dev/null
-
-if [ -s /tmp/.swallowed.$$ ]; then
-  cat /tmp/.swallowed.$$
-  echo "  почини: либо обработай и запиши в лог, либо пробрось дальше."
-  echo "  тихий перехват — это отказ, о котором никто не узнает, пока не станет поздно."
-  rm -f /tmp/.swallowed.$$
-  exit 1
-fi
-rm -f /tmp/.swallowed.$$
-exit 0

package/kit/gates/swallowed-error/green/run.js

@@ -1,8 +0,0 @@
-async function go() {
-  try {
-    await run();
-  } catch (e) {
-    logger.error("шаг не выполнен", e);
-    throw e;
-  }
-}

package/kit/gates/swallowed-error/red/run.js

@@ -1,3 +0,0 @@
-async function go() {
-  try { await run(); } catch (e) {}
-}