houseplan-card/docs/specs/425-core-file-budget.md

# ТЗ #425 — Ядра фронтенда растут только осознанно

- Issue: https://github.com/Matysh/houseplan-card/issues/425
- Приоритет: P2, tech-debt; полный трек — не потому, что задача сложная, а
  потому, что лёгкий трек в этом репозитории не обслуживается конвейером
  («метка small конвейер не запускает»), и ревью ТЗ на нём пришлось бы просить
  у человека. Для гейта, который будет стоять в CI годами, дешевле пройти
  обычную процедуру
- Ревизия: 1 (2026-09-03)
- Заменяет #34 ([HP-ARCH-01]), который закрывается вместе с этой задачей

## Сценарий

Продуктового сценария у задачи нет — она инженерная, и это сказано явно, а не
подразумевается. Разработчик добавляет функцию, кладёт её в ядро, потому что
там уже всё, и ядро прибавляет ещё пятьсот строк. Никто не против: каждый шаг
разумен, а счёт никто не ведёт. Через год 42% кода снова в двух файлах, и
следующая функция стоит дороже предыдущей.

## Что человек увидит до и после

Пользователь — ничего: продуктовый код задача не трогает.

**До**: ядра растут молча, и узнать об этом можно только из аудита, если кто-то
удосужится посчитать.
**После**: рост выше потолка роняет `npm test` и называет цену числом, а
уменьшение требует опустить потолок — то есть выигрыш фиксируется, а не
испаряется.

## Почему не проект, а ограничитель

#34 заведён 09.08, за 25 дней не сдвинулся и шестой аудит подряд отмечается как «без движения». При этом декомпозиция идёт — но не как проект, а попутно: файлов в `src/` было 18 на v1.58, сейчас больше сотни; `houseplan-editor-runtime.ts` выделен из ядра между v1.66 и v1.69; за последние недели отдельными модулями вышли `support-feedback.ts`, `command-stack.ts`, `device-area-relocation.ts`, `danger-confirm.ts`.

Целевая карта каталогов из ТЗ #34 (`app/`, `editors/`, `render/`, `dialogs/`) не реализована и, судя по темпу, не будет. Комментарий от 30.08 в самом #34 это уже признал: «исходная метрика и целевая карта устарели».

**Но долг никуда не делся**, и вот он в числах:

| | card | runtime |
|---|---|---|
| v1.66.0 | 20 287 | — |
| v1.69.0 | 12 824 | 13 290 ← разделение ядра |
| v1.70.0 | 13 603 | 14 287 |
| dev | 13658 | 14322 |

Два файла держат **42%** всего TypeScript в `src/`, и оба растут примерно на 500–1000 строк за релиз: новое уезжает в новые модули, а ядра всё равно прибавляют. Закрыть #34 молча — значит перестать это считать.

## Контракт

Размер двух ядер зафиксирован потолком, и потолок работает **храповиком**:

- ядро выросло выше потолка → отказ с числом: «выросло на N строк, вынесите столько же»;
- ядро уменьшилось заметно ниже потолка → тоже отказ: «опустите потолок на N». Без этой половины выигрыш от любого выноса испарится молча, и через год потолок станет фикцией.

Люфт между «уменьшилось» и «пора опускать потолок» — 250 строк, чтобы обычная правка не требовала трогать константу.

Правило не запрещает расти: оно требует называть цену. Хочешь добавить в ядро — вынеси столько же, и это видно в дифе одной строкой.

## AC

- **AC1**. Рост любого из двух ядер выше потолка роняет `npm test` с сообщением, называющим файл, потолок и превышение в строках. Доказательство: мутант, добавляющий строки в `houseplan-card.ts`, прогнанный штатным раннером.
- **AC2**. Уменьшение ядра больше чем на 250 строк ниже потолка тоже роняет тест — с требованием опустить потолок. Доказательство: юнит на чистой функции.
- **AC3**. Изменение в пределах люфта тест не трогает. Доказательство: тот же юнит.
- **AC4**. Потолки записаны числами в самом тесте: любое их изменение видно в
  дифе и проходит ревью как решение, а не как побочный эффект. Доказательство:
  ревью кода — в тесте нет чтения потолков из внешнего источника (файла,
  переменной окружения, вычисления от текущего размера), и юнит на то, что
  функция принимает потолки аргументом, а не добывает их сама.
- **AC5**. Гейт судит только два ядра. Остальные файлы `src/` не ограничиваются: цель — не заморозить размер кода, а сделать рост ядер осознанным.

## Скоуп / не-скоуп

**В скоупе**: один тест с потолками и храповиком, мутант, строка в
`docs/TESTING.md`, закрытие #34 с объяснением.

**Не в скоупе**: сама декомпозиция (она идёт попутно и продолжит идти), другие
файлы `src/**`, стилевой слой, размер бандла (у него свой бюджет — `#367`).

## UX, модель данных, i18n

Не применимо: продуктового кода задача не касается.

## План автотестов

Логика выносится в чистую функцию `coreBudgetViolations(sizes, caps, slack)` —
тест проверяет её на всех ветках без чтения файлов, и она же вызывается на
реальных ядрах.

1. рост выше потолка → нарушение с числом превышения (AC1);
2. падение ниже потолка больше чем на люфт → нарушение с требованием опустить
   потолок (AC2);
3. изменение в пределах люфта → пусто (AC3);
4. ровно на потолке и ровно на границе люфта → пусто (границы включительно);
5. потолки заданы для обоих ядер и ни для чего больше (AC5).

**Мутант** (`scripts/mutation-gate.mjs`): `core-budget-ignores-growth` —
добавить в `src/houseplan-card.ts` заведомо больше строк, чем люфт, → тест
красный. Мутант правит ЯДРО, а не тест: проверяется, что гейт видит рост
настоящего файла, а не что арифметика сходится сама с собой.

## Риски

- **Потолок будут поднимать не глядя.** Это главный риск любого храповика.
  Смягчение: число живёт в тесте, его изменение попадает в дифф и проходит
  ревью как решение; сообщение об отказе прямо называет альтернативу — вынести
  столько же строк.
- **Строки — грубая мера.** Файл можно «уменьшить», сжав форматирование.
  Смягчение: мера и не претендует на точность, она нужна как сигнал; ревью
  видит дифф и отличает вынос от переупаковки.
- **Люфт 250 строк может оказаться мал или велик.** Смягчение: он записан
  константой рядом с потолками, меняется тем же порядком и с тем же ревью.

## Откат

Удаление одного тестового файла и одного мутанта.

## Release-артефакты

- `docs/CHANGELOG.md` / `docs/CHANGELOG.ru.md`: **не требуется**
  (User-Visible: no).
- `docs/TESTING.md`: правило и что делать, когда гейт покраснел.