fullstack-gates 0.1.0

package/scripts/check-debt.ts

@@ -0,0 +1,260 @@
+#!/usr/bin/env bun
+/**
+ * ГЕЙТ ДОЛГОВ — сознательно не сделанное обязано быть названным, счётным и найденным при правке.
+ *
+ * ─── ЗАЧЕМ ОН ПОЯВИЛСЯ ──────────────────────────────────────────────────────────────────────────
+ *
+ * Случай, с которого он начался: эмиттер схемы не создал индексы, объявленные моделью данных, и
+ * записал причину КОММЕНТАРИЕМ В КОДЕ: «параметры зависят от объёма, объём не задан». Рассуждение
+ * выглядело взвешенным, поэтому дыру никто не искал. Поймать её не мог никто:
+ *
+ *   • гейт `schema-emit` считал таблицы, перечисления и внешние ключи — индексы не считал;
+ *   • ни один критерий приёмки не про физическую схему: все они про ПОВЕДЕНИЕ;
+ *   • `BUILD_COMPLETE` напечатался честно — по своим условиям он и был выполнен.
+ *
+ * Итог: поиск ходил полным сканом, отчёт был зелёный, а владелец узнал об этом сам, глазами. Долг
+ * существовал, был обоснован и был невидим — и невидимость здесь опаснее самого долга.
+ *
+ * ─── ЧЕМ ЭТО НЕ TODO ───────────────────────────────────────────────────────────────────────────
+ *
+ * `TODO` в коде не считается, не истекает и ни на что не влияет: его пишут, чтобы успокоить себя.
+ * Долг здесь — ЗАПИСЬ В РЕЕСТРЕ, у которой есть цена и условие снятия, она печатается очередью и
+ * попадает в финальный отчёт сборки рядом с отметкой. `BUILD_COMPLETE` и «долгов: 7» видны вместе,
+ * и это единственное, что отличает законченную работу от объявленной законченной.
+ *
+ * ─── ПРИВЯЗКА ДВУСТОРОННЯЯ, И В ЭТОМ ВСЯ СИЛА ──────────────────────────────────────────────────
+ *
+ * Ссылка из кода на несуществующий долг — ошибка. Долг, на который ничто в коде не ссылается, —
+ * тоже ошибка: реестр, живущий отдельно от кода, устаревает первым, и через месяц никто не знает,
+ * снят долг или про него забыли. Тот же шов, что связывает критерий приёмки с тестом.
+ *
+ * Долг, которому в коде физически не на что повеситься (не сделан целый слайс, не куплено железо),
+ * объявляет это явно — `@нет-якоря` в поле разблокировки.
+ *
+ *   bun run check:debt          печатает таблицу, падает на браке формата
+ *   bun run check:debt --quiet  только код возврата
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const ROOT = process.cwd();
+const РЕЕСТР = join(ROOT, "scripts/debt.open");
+
+/** Форма записи. Разделитель полей — ` · `, потому что в тексте долга бывает всё остальное. */
+const ФОРМАТ =
+  "DEBT-NNN  <область>  <ГГГГ-ММ-ДД>  <что не сделано> · <чем снимается> · <цена, если не снять>";
+
+export interface Долг {
+  id: string;
+  область: string;
+  заявлен: Date;
+  что: string;
+  снимается: string;
+  цена: string;
+  /** Долг объявил, что в коде якоря нет и быть не может. */
+  безЯкоря: boolean;
+  строка: number;
+}
+
+export interface Находка {
+  строка: number;
+  текст: string;
+  причина: string;
+}
+
+const ISO = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Разбор реестра. Каждая ошибка — НАХОДКА, а не исключение: строка с браком не должна прятать
+ * остальные, иначе первая же опечатка скроет девять исправных долгов.
+ */
+export function разобрать(текст: string, сегодня: Date): { долги: Долг[]; находки: Находка[] } {
+  const долги: Долг[] = [];
+  const находки: Находка[] = [];
+  const виденные = new Set<string>();
+
+  текст.split("\n").forEach((raw, i) => {
+    const строка = i + 1;
+    const line = raw.split("#")[0]!.trim();
+    if (!line) return;
+
+    const m = /^(\S+)\s+(\S+)\s+(\S+)\s+(.+)$/.exec(line);
+    if (!m) {
+      находки.push({ строка, текст: line, причина: `не разбирается. Форма: ${ФОРМАТ}` });
+      return;
+    }
+    const [, id, область, дата, хвост] = m as unknown as [string, string, string, string, string];
+
+    if (!/^DEBT-\d{3,}$/.test(id)) {
+      находки.push({ строка, текст: line, причина: `«${id}» — не идентификатор долга (DEBT-NNN)` });
+      return;
+    }
+    // Дубль идентификатора страшнее опечатки: ссылка из кода станет вести в два места сразу.
+    if (виденные.has(id)) {
+      находки.push({ строка, текст: line, причина: `${id} объявлен второй раз` });
+      return;
+    }
+    виденные.add(id);
+
+    if (!ISO.test(дата) || Number.isNaN(Date.parse(дата))) {
+      находки.push({ строка, текст: line, причина: `«${дата}» — не дата ГГГГ-ММ-ДД` });
+      return;
+    }
+    const заявлен = new Date(`${дата}T00:00:00Z`);
+    // Долг из будущего — почти всегда опечатка в годе, и она тихо отключила бы счётчик возраста.
+    if (заявлен.getTime() > сегодня.getTime()) {
+      находки.push({ строка, текст: line, причина: `дата ${дата} в будущем` });
+      return;
+    }
+
+    const части = хвост.split("·").map((с) => с.trim());
+    if (части.length !== 3 || части.some((с) => с.length === 0)) {
+      находки.push({
+        строка,
+        текст: line,
+        причина: `нужны ТРИ поля через « · »: что не сделано · чем снимается · цена. Дано: ${части.length}`,
+      });
+      return;
+    }
+    const [что, снимается, цена] = части as [string, string, string];
+
+    /**
+     * ЦЕНА ОБЯЗАТЕЛЬНА, и это не формальность. Долг без цены неотличим от предпочтения: по нему
+     * нельзя решить, брать его сейчас или через полгода, — а решать это и есть единственное, ради
+     * чего реестр существует.
+     */
+    долги.push({
+      id,
+      область,
+      заявлен,
+      что,
+      снимается: снимается.replace(/@нет-якоря/g, "").trim() || снимается,
+      цена,
+      безЯкоря: /@нет-якоря/.test(снимается),
+      строка,
+    });
+  });
+
+  return { долги, находки };
+}
+
+/* ─────────────────────────── Привязка к коду ─────────────────────────── */
+
+const ПРОПУСК = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".turbo",
+  "coverage",
+  ".next",
+  "drizzle",
+]);
+const РАСШИРЕНИЯ = /\.(ts|tsx|js|jsx|mjs|sql|md|json|yaml|yml)$/;
+
+function файлы(dir: string, найдено: string[] = []): string[] {
+  for (const имя of readdirSync(dir)) {
+    if (ПРОПУСК.has(имя)) continue;
+    const путь = join(dir, имя);
+    if (statSync(путь).isDirectory()) файлы(путь, найдено);
+    else if (РАСШИРЕНИЯ.test(имя)) найдено.push(путь);
+  }
+  return найдено;
+}
+
+/** Где в коде упомянут каждый идентификатор долга. Сам реестр не считается ссылкой на себя. */
+export function ссылкиИзКода(root: string): Map<string, string[]> {
+  const карта = new Map<string, string[]>();
+  for (const путь of файлы(root)) {
+    if (путь === РЕЕСТР) continue;
+    const текст = readFileSync(путь, "utf8");
+    for (const m of текст.matchAll(/DEBT-\d{3,}/g)) {
+      const id = m[0];
+      карта.set(id, [...(карта.get(id) ?? []), relative(root, путь)]);
+    }
+  }
+  return карта;
+}
+
+/* ─────────────────────────────── Прогон ─────────────────────────────── */
+
+export function проверить(
+  текст: string,
+  ссылки: Map<string, string[]>,
+  сегодня: Date
+): { долги: Долг[]; находки: Находка[] } {
+  const { долги, находки } = разобрать(текст, сегодня);
+  const объявленные = new Set(долги.map((д) => д.id));
+
+  for (const д of долги) {
+    const где = ссылки.get(д.id) ?? [];
+    if (где.length === 0 && !д.безЯкоря) {
+      находки.push({
+        строка: д.строка,
+        текст: д.id,
+        причина:
+          "на долг ничто не ссылается из кода. Поставь `DEBT-NNN` там, где принято решение " +
+          "не делать, — иначе при правке этого места о долге не узнают. " +
+          "Якоря нет и быть не может — напиши `@нет-якоря` в поле разблокировки",
+      });
+    }
+  }
+
+  for (const [id, где] of ссылки) {
+    if (!объявленные.has(id)) {
+      находки.push({
+        строка: 0,
+        текст: id,
+        причина: `код ссылается на долг, которого нет в реестре: ${где.slice(0, 3).join(", ")}`,
+      });
+    }
+  }
+
+  return { долги, находки };
+}
+
+if (import.meta.main) {
+  const тихо = process.argv.includes("--quiet");
+  const сегодня = new Date();
+
+  if (!existsSync(РЕЕСТР)) {
+    // Отсутствие реестра — не «долгов нет», а «механизма нет». Разница существенная.
+    const ссылки = ссылкиИзКода(ROOT);
+    if (ссылки.size > 0) {
+      console.error(`✗ код ссылается на долги (${[...ссылки.keys()].join(", ")}), а ${РЕЕСТР} нет`);
+      process.exit(1);
+    }
+    if (!тихо)
+      console.log("долгов: 0 (реестра нет — заведи scripts/debt.open, когда появится первый)");
+    process.exit(0);
+  }
+
+  const { долги, находки } = проверить(readFileSync(РЕЕСТР, "utf8"), ссылкиИзКода(ROOT), сегодня);
+
+  if (!тихо) {
+    if (долги.length === 0) console.log("долгов: 0");
+    else {
+      console.log(`долгов: ${долги.length}\n`);
+      const дней = (д: Долг) => Math.floor((сегодня.getTime() - д.заявлен.getTime()) / 86_400_000);
+      for (const д of [...долги].sort((a, b) => a.заявлен.getTime() - b.заявлен.getTime())) {
+        const возраст = дней(д);
+        // Возраст печатается ВСЕГДА: долг, которому полгода, — это уже решение, а не отсрочка.
+        console.log(`${д.id}  ${д.область}  ${возраст} дн.`);
+        console.log(`   не сделано: ${д.что}`);
+        console.log(`   снимается:  ${д.снимается}${д.безЯкоря ? "  (якоря в коде нет)" : ""}`);
+        console.log(`   цена:       ${д.цена}\n`);
+      }
+    }
+  }
+
+  if (находки.length > 0) {
+    console.error(`✗ брак в реестре долгов (${находки.length}):`);
+    for (const н of находки) {
+      console.error(
+        `  ${н.строка ? `${РЕЕСТР}:${н.строка}` : "код"}  ${н.текст}\n    ${н.причина}`
+      );
+    }
+    process.exit(1);
+  }
+  process.exit(0);
+}

package/scripts/check-pins.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env bun
+/**
+ * `bun run check:pins` — в объявлениях зависимостей нет плавающих версий.
+ *
+ * ЧТО ЛОВИТ. `"latest"` и `"*"` в `dependencies`/`devDependencies` любого пакета воркспейса.
+ * Такое объявление означает «что окажется новым в день установки». Пока цел `bun.lock`, оно молчит:
+ * свежий клон получает версии из локфайла, и всё выглядит воспроизводимым. Оно просыпается на
+ * `bun update`, на добавлении пакета и на любом резолве без локфайла — то есть тогда, когда никто
+ * не связывает поломку с объявлением, сделанным полгода назад.
+ *
+ * ЦЕНОЙ ЧЕГО ЭТО ПОНЯЛИ. 2026-08-26 `@tanstack/react-query: "latest"` разрешился в `5.102.5`, чей
+ * `query-core` в реестре не опубликован, и `bun install` перестал проходить в репозитории, где не
+ * меняли ничего. Починка была одна: дописать строку в `overrides`. Так и росла куча — симптом лечили,
+ * причину оставляли, и продукт наследовал кучу, в которой уже не отличить нужное от инерции.
+ *
+ * ПОЧЕМУ НЕ ПРОСТО «ЗАПРЕТИТЬ ЛЮБОЕ *». `peerDependencies` намеренно оставлены снаружи: там `"*"`
+ * значит «совместим с тем, что выберет приложение», и это не резолв, а объявление совместимости.
+ * Запрет там заставил бы пакет ядра диктовать продукту версию React — ровно то, чего швы избегают.
+ *
+ * ТОЧНО или КАРЕТКОЙ — решает роль пакета:
+ *   ТОЧНО (`7.0.2`)     компилятор и его типы. Их плавание меняет РЕЗУЛЬТАТ `bun run check`
+ *                       между машинами: тайпчек — это и есть проверка, и она не должна зависеть от
+ *                       дня установки.
+ *   КАРЕТКОЙ (`^1.2.3`) остальное: патчи и миноры приезжают, мажор — решение человека.
+ */
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+const ROOT = existsSync(join(process.cwd(), "package.json"))
+  ? resolve(process.cwd())
+  : resolve(import.meta.dir, "..");
+
+/** Определяют вердикт проверки — только точная версия. */
+const ТОЧНО = new Set([
+  "typescript",
+  "@types/bun",
+  "@types/node",
+  "@types/react",
+  "@types/react-dom",
+  "oxlint",
+  "oxfmt",
+]);
+
+const ПЛАВАЮЩИЕ = new Set(["*", "latest"]);
+
+function манифесты(): string[] {
+  const out = [join(ROOT, "package.json")];
+  for (const каталог of ["packages", "apps"]) {
+    const корень = join(ROOT, каталог);
+    if (!existsSync(корень)) continue;
+    for (const e of readdirSync(корень, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      const p = join(корень, e.name, "package.json");
+      if (existsSync(p)) out.push(p);
+    }
+  }
+  return out;
+}
+
+const плавающие: string[] = [];
+const нестрогие: string[] = [];
+
+const файлы = манифесты();
+for (const путь of файлы) {
+  const pkg = JSON.parse(readFileSync(путь, "utf8"));
+  for (const секция of ["dependencies", "devDependencies"] as const) {
+    for (const [имя, версия] of Object.entries<string>(pkg[секция] ?? {})) {
+      // Воркспейс-ссылки — не версии реестра, их этот гейт не касается.
+      if (версия.startsWith("workspace:")) continue;
+      const где = `${relative(ROOT, путь)} → ${секция} → ${имя}`;
+      if (ПЛАВАЮЩИЕ.has(версия)) плавающие.push(`${где} = "${версия}"`);
+      else if (ТОЧНО.has(имя) && /^[\^~]/.test(версия))
+        нестрогие.push(`${где} = "${версия}" (нужна точная)`);
+    }
+  }
+}
+
+/**
+ * Пустой список файлов — это ПРОВАЛ, а не «нарушений нет».
+ * Гейт, которому нечего проверять, зелен ровно так же, как гейт, проверивший всё.
+ */
+if (файлы.length === 0) {
+  console.error("check:pins: не найдено ни одного package.json — проверять нечего.");
+  process.exit(1);
+}
+
+if (плавающие.length === 0 && нестрогие.length === 0) {
+  console.log(`pins: манифестов ${файлы.length} · плавающих версий нет`);
+  process.exit(0);
+}
+
+if (плавающие.length) {
+  console.error(`\n❌ плавающие версии (${плавающие.length}):`);
+  for (const s of плавающие) console.error(`   ${s}`);
+  console.error(
+    "\n   Замени на диапазон той версии, что стоит сейчас: она уже проверена этими уровнями.\n" +
+      "   Посмотреть установленное: bun pm ls | grep <пакет>"
+  );
+}
+if (нестрогие.length) {
+  console.error(`\n❌ каретка там, где нужна точная версия (${нестрогие.length}):`);
+  for (const s of нестрогие) console.error(`   ${s}`);
+  console.error(
+    "\n   Это компилятор и его типы: их версия меняет РЕЗУЛЬТАТ тайпчека, а не только поведение\n" +
+      "   приложения. Проверка, зависящая от дня установки, — не проверка."
+  );
+}
+process.exit(1);

package/scripts/check-priority.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+/**
+ * `bun run check:priority` — объявления приоритета в спеке действительны.
+ *
+ * ─── ЗАЧЕМ ГЕЙТ, А НЕ ПРОСТО УМОЛЧАНИЕ ───────────────────────────────────────────────────────────
+ *
+ * Приоритет — единственное поле спеки, которое МЕНЯЕТ ПОРЯДОК РАБОТ, и единственное, у которого
+ * ошибка выглядит как решение. `priority: heigh` при молчаливом умолчании даёт слайсу `normal`:
+ * владелец написал «первым», получил «как все», и ни одна строка вывода этого не скажет. Ровно тот
+ * класс лжи, против которого написаны остальные гейты этой репы, — только применённый к очереди,
+ * то есть к тому, ЧТО будет построено раньше.
+ *
+ * Поэтому недействительное объявление краснеет здесь, а `bun run next-slice` печатает его вслух.
+ * Два разных места: гейт останавливает, очередь показывает. Одно без другого либо ломает сборку
+ * без объяснения, либо объясняет, ничего не останавливая.
+ *
+ * ─── ЧЕГО ЗДЕСЬ НЕТ ──────────────────────────────────────────────────────────────────────────────
+ *
+ * Суждения о том, ВЕРЕН ли приоритет. «Поиску не место в high» — это разговор с владельцем, а не
+ * находка гейта; гейт, взявшийся судить о ценности, начинает ошибаться, и первое, что с ним
+ * делают, — отключают. Здесь проверяется только форма: значение из закрытого множества, причина
+ * названа, спутники не осиротели.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+import { parsePriority, PRIORITIES, type Priority } from "./lib/priority.ts";
+
+/** Корень РЕПЫ, а не скрипта: скрипт живёт в плагине и запускается из чужого дерева. */
+const ROOT = existsSync(join(process.cwd(), "package.json"))
+  ? resolve(process.cwd())
+  : resolve(import.meta.dir, "..");
+
+export interface Находка {
+  path: string;
+  error: string;
+}
+
+export interface Свод {
+  находки: Находка[];
+  /** Сколько слайсов в каждой полосе (недействительные считаются по действующему значению). */
+  полосы: Record<Priority, number>;
+  /** Слайсов без объявления. Работают как `normal`, но решения за ними нет. */
+  безОбъявления: number;
+  всего: number;
+}
+
+/**
+ * Проверка НАД СПИСКОМ, а не над каталогом.
+ *
+ * Так она проверяема тестом без временных файлов: обход диска — это ввод, а не правило.
+ */
+export function проверить(файлы: { path: string; source: string }[]): Свод {
+  const свод: Свод = {
+    находки: [],
+    полосы: { high: 0, normal: 0, low: 0 },
+    безОбъявления: 0,
+    всего: файлы.length,
+  };
+  for (const f of файлы) {
+    const p = parsePriority(f.source);
+    свод.полосы[p.value]++;
+    if (p.error) свод.находки.push({ path: f.path, error: p.error });
+    else if (!p.declared) свод.безОбъявления++;
+  }
+  return свод;
+}
+
+/**
+ * Файлы слайсов — те, что несут `feature:` в шапке.
+ *
+ * Тем же признаком их находит `bun run ac` и `bun run next-slice`: сгенерированные своды
+ * (`index.md`, `catalogue.md`) его не несут, и это единственное, чем файл модуля отличается от
+ * указателя на модули.
+ */
+function собратьФайлы(dir: string): { path: string; source: string }[] {
+  if (!existsSync(dir)) return [];
+  const out: { path: string; source: string }[] = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) out.push(...собратьФайлы(full));
+    else if (e.name.endsWith(".md")) {
+      const source = readFileSync(full, "utf8");
+      if (/^feature:\s*\S/m.test(source)) out.push({ path: full, source });
+    }
+  }
+  return out;
+}
+
+if (import.meta.main) {
+  const usecases = join(ROOT, "docs/usecases");
+  const файлы = собратьФайлы(usecases);
+  if (файлы.length === 0) {
+    // Пустой каталог — не «нарушений нет». Тот же отказ, что у `ac`: зелёный на пустоте.
+    console.error(
+      `check:priority: в ${relative(ROOT, usecases)} нет ни одного файла слайса с \`feature:\` в шапке.\n` +
+        "Проверять нечего — а зелёный прогон на пустоте неотличим от пройденной проверки."
+    );
+    process.exit(1);
+  }
+  const свод = проверить(файлы);
+
+  for (const н of свод.находки) {
+    console.log(`НЕДЕЙСТВИТЕЛЬНО: ${relative(ROOT, н.path)}\n    ${н.error}`);
+  }
+  const полосы = PRIORITIES.map((p) => `${p} ${свод.полосы[p]}`).join(" · ");
+  console.log(
+    `priority: слайсов ${свод.всего} · ${полосы} · без объявления ${свод.безОбъявления} · ` +
+      `недействительных ${свод.находки.length}`
+  );
+  if (свод.находки.length) {
+    console.error(
+      `\nПриоритет объявляется в шапке файла слайса и ТРЕБУЕТ причины:\n` +
+        `    priority: high            # ${PRIORITIES.join(" | ")}\n` +
+        `    priority-by: owner        # owner (не сбрасывается перегенерацией) | derived\n` +
+        `    priority-why: "основной путь продукта: REQ-MCP-01"\n`
+    );
+  }
+  process.exit(свод.находки.length ? 1 : 0);
+}