agent-quality-kit 0.5.0 → 0.7.0

package/tool/selfcheck/units.mjs

@@ -11,8 +11,9 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { parseManifest, manifestWithGate, unknownKeys } 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, 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";
@@ -274,3 +275,197 @@ test("триггер по интерфейсу отделяет фронтенд
   // Причина сокрытия называется, а не молчит: иначе «не показано» неотличимо от «нечего показать».
   assert.equal(typeof triggerVerdict(rec, { ...base, has_ui: false }).why, "string");
 });
+
+// --- зрелость записи ---------------------------------------------------------
+// ЗАЧЕМ. У всех трёх соседей поле зрелости есть, и у всех троих его ЗАПОЛНЯЕТ АВТОР: `lifecycle`
+// у зондов Scorecard, `future`/`obsolete` у критериев значка OpenSSF. Поле, которое объявляет
+// автор, означает доверие к автору, а не факт, — ровно то, против чего построен весь стандарт.
+// Поэтому зрелость здесь ВЫЧИСЛЯЕТСЯ из доказательства, а объявить её нельзя.
+test("зрелость записи считается по доказательству, а не по объявлению", () => {
+  const proven = entryLifecycle({ proof: "incidents/README.md, 2026-08-27 «печать в проде»" });
+  assert.equal(proven.state, "stable");
+  assert.equal(proven.problem, null);
+
+  const claimed = entryLifecycle({ proof: "это общепринятая хорошая практика" });
+  assert.equal(claimed.state, "experimental");
+  assert.equal(claimed.problem, null);
+  // Причина обязательна: «запись условная» без объяснения неотличимо от придирки.
+  assert.equal(typeof claimed.why, "string");
+});
+
+test("объявить себя зрелым нельзя — это самооценка", () => {
+  for (const claim of ["stable", "experimental"]) {
+    const r = entryLifecycle({ lifecycle: claim, proof: "incidents/README.md, 2026-01-01" });
+    assert.notEqual(r.problem, null);
+    // Вердикт всё равно считается сам: объявление не влияет ни на что, кроме отказа.
+    assert.equal(r.state, "stable");
+  }
+  assert.notEqual(entryLifecycle({ lifecycle: "beta", proof: "incidents/x" }).problem, null);
+});
+
+// Единственное состояние, которое ОБЪЯВЛЯЕТСЯ: из фактов записи «её больше не ставят» не
+// выводится никак. Цена объявления — обязательная замена: запись, выведенная в никуда,
+// оставляет человека без ответа на вопрос «а что теперь».
+test("выведенная запись обязана назвать замену", () => {
+  const noReplacement = entryLifecycle({ lifecycle: "deprecated", proof: "incidents/x" });
+  assert.equal(noReplacement.state, "deprecated");
+  assert.notEqual(noReplacement.problem, null);
+
+  const ok = entryLifecycle({ lifecycle: "deprecated", superseded_by: "no-print-in-prod", proof: "incidents/x" });
+  assert.equal(ok.state, "deprecated");
+  assert.equal(ok.supersededBy, "no-print-in-prod");
+  assert.equal(ok.problem, null);
+});
+
+
+// --- сужение вывода до дифа --------------------------------------------------
+// ЗАЧЕМ. Первый прогон на живом проекте даёт тысячи находок из кода, который писали годами.
+// Человек видит стену красного и выключает инструмент целиком — это причина номер один, по
+// которой такие проверки снимают. Три независимых проекта из нашего разбора умеют показывать
+// только внесённое дифом (reviewdog, ratchets `--since`, четыре режима шума у react-doctor).
+test("сужение по дифу: находка вне диапазона отбрасывается, внутри — остаётся", () => {
+  const files = new Set(["src/new.py"]);
+  const r = scopeOutput(["src/new.py:3: печать", "src/old.py:9: печать"], files);
+  assert.deepEqual(r.kept, ["src/new.py:3: печать"]);
+  assert.equal(r.findings, 1);
+});
+
+test("сужение по дифу: «./путь» и «путь» — один и тот же файл", () => {
+  const r = scopeOutput(["./src/new.py:3: печать", "src\\new.py:4: печать"], new Set(["src/new.py"]));
+  assert.equal(r.findings, 2);
+});
+
+// Тот же урок, что стоил починки в _native.sh: родные инструменты печатают путь ВНУТРИ
+// escape-последовательности, и сравнение по границе пути его не видит. Тогда «вывод
+// сократился с 5597 до 5505 строк» выглядело как работающая правка.
+test("сужение по дифу: цвет снимается до сравнения путей", () => {
+  const esc = String.fromCharCode(27);
+  const line = esc + "[32m" + "src/new.py" + esc + "[0m" + ":3: печать";
+  assert.equal(scopeOutput([line], new Set(["src/new.py"])).findings, 1);
+});
+
+test("сужение по дифу: строка без пути остаётся, но находкой не считается", () => {
+  const r = scopeOutput(["Итого: 4 нарушения", "src/old.py:1: печать"], new Set(["src/new.py"]));
+  assert.equal(r.findings, 0);
+  assert.equal(r.kept.includes("Итого: 4 нарушения"), true);
+});
+
+// САМОЕ ВАЖНОЕ ЗДЕСЬ. Гейт, который печатает вердикт без путей (проверка коммита, проверка
+// конфига конвейера), сузить дифом нельзя. Молча признать его успешным — это ровно та тишина,
+// против которой построен весь стандарт, только теперь внутри нашего же флага.
+test("сужение по дифу: гейт без путей в выводе не сужается и остаётся красным", () => {
+  const r = scopeOutput(["коммит не несёт раздела «Сделано:»"], new Set(["src/new.py"]));
+  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) {}
-}