@vernikr/size-report 1.1.1

package/README.md

@@ -0,0 +1,892 @@
+# @vernikr/size-report
+
+Инструмент учёта роста объёма кода и документов: показывает, насколько вырос или
+уменьшился проект в каждом изменении, в трёх разрезах — «как написано» (raw),
+«в минифицированном виде» (min) и «в токенах для языковой модели» (tok).
+
+Отвечает на два вопроса: человеку — «где проект распухает», ИИ-агенту — «сколько
+весит моё изменение в его собственном контексте». Ничего не запрещает и не
+блокирует: только показывает.
+
+## Статус
+
+**Выпуск 1.1.1 (2026-09-15).** Инструмент живёт отдельным пакетом: имя в
+реестре — `@vernikr/size-report` (выпуск переименования, числа не изменились).
+Версия — в манифесте, а у выпуска есть `CHANGELOG.md` с разделом «Что изменится
+в числах»:
+таблица чисел в нём не пересказ, а замер на фикстуре, который сверяется с живым
+прогоном (`test/changelog.test.js`). Числа этим выпуском не меняются — правки
+лежат в ответах инструмента человеку; `schema: 1` данных, замороженная 1.0.0,
+остаётся той же.
+
+**Шаг 1 плана пройден — перенос без изменения поведения.** Команда —
+`bin/size.js`, точка входа пакета — `src/size-table.js` (только реэкспорт),
+механика разложена по модулям `src/`; паритет доказан автоматически:
+`pnpm test` сверяет пакет с эталоном побайтово на фикстуре и в четырёх заведомо
+чужих окружениях (настройки git машины, локаль), `pnpm run parity:live` — на живой
+истории `safe-resets` в двух средах (95 строк × 27 колонок, артефакт байт в байт).
+Вывод не зависит от настроек машины — настройки git, влияющие на разбор, закреплены
+в самом движке (`BLOCKERS.md` §B1). Сверка с рабочим деревом сравнивает содержимое,
+а не размеры, поэтому выкладка с переводами строк в CRLF (`.gitattributes`,
+`core.autocrlf` — значение по умолчанию в установке Git для Windows) работе не
+мешает (`BLOCKERS.md` §B2).
+
+**История с удалениями больше не тупик** (`BLOCKERS.md` §B3). Колонка, чей файл жил
+в истории и был удалён до HEAD, роняла прогон **кодом 1** с текстом «файла нет
+вместо файла нет» — то есть на проекте с удалёнными файлами отчёта не было вовсе.
+Теперь отказом считается **расхождение** сторон сверки, а не пустота с обеих:
+потерянное создание, потерянное изменение и потерянное удаление по-прежнему роняют
+прогон — но с настоящей причиной и готовой командой, а файл, удалённый до HEAD,
+просто пуст в таблице. Доказано числами, а не словом: размер колонки на каждом
+коммите сверяется с размером блоба из git (возврат файла даёт то же число, что его
+первое появление), а второй свидетель — файл, который появляется только в слиянии,
+— роняет прогон и называет обе стороны: «в дереве `src/only-in-merge.js` 77d3e2f, в
+состоянии файла нет». Заодно закрыта граница того же разбора (`BLOCKERS.md` §N8):
+путь для состояния выбирался по порядку настроек, а не по тому, что в коммите есть,
+поэтому при `diff.renames=false` — когда git отдаёт в одном коммите и старое имя
+переименованного файла, и новое — движок брал исчезнувшее и сверка отказывала на
+законном случае. Теперь берётся тот псевдоним колонки, для которого git отдал блоб.
+Прежние числа поехать не могли: обе логики совпадают всюду, где первый по порядку
+псевдоним в коммите существует, то есть в любом прогоне, который до сих пор
+заканчивался отчётом. Это проверено, а не заявлено: вывод движка до и после правки
+совпал побайтово на фикстуре при `diff.renames` в обоих значениях, оба эталона
+воспроизводятся байт в байт, живой отчёт — те же 95 × 27 и 225 673 Б, а прогон на
+живой истории остался 1,56–1,58 с.
+
+**Подключение к проекту-потребителю сделано (2026-09-14, шаг 5 плана).**
+`safe-resets` ставит пакет из git по тегу выпуска и больше не держит своей копии
+инструмента: ни `tools/size-table.js`, ни его теста — таблицу собирает и
+проверяет команда `size` (`pnpm run test:sizes`), а её шаги в проекте — одна
+строка в раннере (`WORKLOG.md` §18). Инструкция подключения оказалась верна, а
+двух вещей в ней не было: шага доступа к пакету в CI и порядка переезда с уже
+лежащей копии — оба дописаны в её же раздел («Как подключить»); шаг с ключом
+оттуда потом ушёл вместе с приватностью (§1).
+
+**Шаг 2 начат первым срезом — контрактом данных.** Движок отдаёт абсолютные
+значения и устройство таблицы (`--data`), а дельты, суммы, «сейчас» и фильтры
+считает страница (`--page`, `size-report.html` рядом с таблицей): без этого
+фильтры и «итого по выбору» невозможны в принципе. В контракте едет и точность
+числа — рядом пометок `approx` по клеткам, — потому что это факт замера, а не
+вывод: страница показывает то, что сказал движок, и своего правила точности не
+заводит. Панель страницы — дерево файлов по папкам, с переключателем у каждой
+папки на всё поддерево; выбор читателя переживает перезаход и передаётся
+ссылкой — адрес страницы и есть ссылка.
+Минификация и токены сделаны первыми срезами шагов 3 и 4 (ниже).
+Разбиение движка по файлам сделано (пункт D1 плана, R-1.3 `REFACTOR.md`).
+Источник инструмента — скрипт `size-table.js` (1145 строк) в проекте
+[`safe-resets`](../figma/safe-resets) (метрики `raw` и «упрощение вместо
+минификации», статичный отчёт в git); в этом репозитории такого пути нет, и
+дальше он не упоминается без имени проекта.
+**Пункт R-1.2 волны 1** (`REFACTOR.md`): в пакете есть линтер — правила те же, что у
+проекта-потребителя, плюс запрет склейки операторов в одну строку; всё настоящее
+дерево (37 файлов) даёт ноль замечаний, `fixtures/` не линтуются — там данные.
+
+**Пункты R-1.1 и R-2.1 волн 1–2** (`REFACTOR.md`): вычислительная часть отчёта одна
+(`src/derived.js`) — страница исполняет тот же код, что считает статическую таблицу,
+и разметку для неё строит обычный исходник `src/page/app.js`, а не строка внутри
+движка; артефакт и разметка страницы при этом совпали со старым выводом побайтово.
+
+**Отчёт собирается и в проекте с модулями в `.js`** (`REFACTOR.md` R-4.6): гард
+стриппера понимает обе формы — скрипт и модуль, — поэтому подключение не требует
+ни одной правки настроек руками, а когда в графе и правда не JavaScript, отказ
+называет причину и команду. Подсказки, справка, умолчание команды починки и
+шаблоны называют **путь внутри проекта** (`node node_modules/@vernikr/size-report/bin/size.js`),
+а не имя пакета: `npx <имя>` запускает установленный пакет, только пока тот на
+месте, а в проекте без него это имя уходит в реестр и тянет пакет по сети
+(`R-4.7` — прежнее решение, `R-4.21` — почему оно отменено).
+
+**У обещаний документации есть сторож** (`REFACTOR.md` R-4.1): он разложен по
+обещаниям, поэтому у каждого свой дом — `test/docs-paths.test.js` (пути из текста
+есть в дереве, таблица файлов сходится с ним в обе стороны),
+`test/docs-commands.test.js` (команды и ключи есть в справке, причины отказа
+совпадают с реестром движка, ссылки на разделы ведут в существующие),
+`test/docs-numbers.test.js` (числа проверок и целей — факт) и
+`test/docs-pin.test.js` (пример установки ведёт на ревизию, чья справка знает
+названные команды), а с выпуском добавился пятый — `test/changelog.test.js`
+(версия выпуска — версия манифеста, а таблица «что изменится в числах» — не
+пересказ, а замер на фикстуре, сверенный с живым прогоном); читатель фактов один —
+`tools/docs-facts.js`. Заведённый сторож сразу
+нашёл четыре расхождения, и все починены: таблица файлов не называла
+`fixtures/live/README.md`, `test/runner.test.js` и сам файл сторожа, `README.md`
+обещал 92 проверки при 97, а две ссылки `PLAN.md` вели в разделы, которых в названных
+документах нет. Чего машиной не проверить — формулировок, обещаний о будущем и
+верности описания роли файла — сторож за собой не берёт и говорит об этом в шапке.
+
+**git читается через одну границу — и в проверках тоже** (`REFACTOR.md` R-1.4).
+Список закреплений (`core.quotePath`, раскраска, подпись, кодировка) один на движок и
+обвязку: проверки и инструменты зовут git через общее место, а незакреплённое
+место стережёт `test/git-pins.test.js` — и он же свидетелем показывает, что
+закрепление работает: то же чтение без него отдаёт не-английский путь кавычками, с
+ним — как есть. Это тот же дефект, что B1, только найденный в обвязке: без
+закрепления проверка зелена на машине с нашими настройками и красна на машине с
+настройками по умолчанию. У проверки, которая измеряет само окружение,
+незакреплённое чтение осталось намеренно — оно названо и стоит в отдельном списке.
+
+**Каждый отказ инструмента говорит правду — и это сторожится, а не подразумевается**
+(`REFACTOR.md` R-4.18). Ложную причину в тексте отказа находил живой прогон, и находил
+четыре раза подряд (B1, B3, разбор аргументов, `explain HEAD`) — каждый раз случайно.
+Класс закрыт не пятым исправлением: в `tools/refusals.js` лежит по строке на каждый
+отказ — что он обязан донести, каким кодом ответить и какие фразы в выводе обязаны
+остаться, — а две проверки делят обе половины обещания. `test/refusals.test.js`
+**вызывает** тридцать два отказа (тридцать три запуска инструмента, включая чужие
+клоны для хука, обрезанной истории и ветки мимо отчёта) и сверяет код выхода и
+фразы; `test/refusals-catalog.test.js` читает исходники и требует, чтобы у каждого
+места отказа был свой пункт (карты `SITES` и `PRINTED` держат числа мест), а у
+каждого пункта — случай в каталоге, — то есть новый отказ не может появиться без
+проверки. Отказы, которых прогоном не поймать,
+названы явно: четыре стережёт своя проверка (в каталоге записаны её файл и фразы),
+а один не поймать вовсе — «внутренняя ошибка» — и там же сказано, почему. Чего
+каталог не берёт, сказано словами: формулировки вне перечисленных фраз, смысл, и
+знак «!» — это примечание (приближение, смешанный коммит, выключенная автоматика),
+а не отказ, и код выхода у него нулевой.
+
+**И совет в отказе исполним — это тоже проверяется.** Правда о причине — половина
+обещания: вторая — что предложенную команду можно выполнить. Поводом стал живой
+случай (R-4.21): подсказка звала по имени из реестра, где пакета с таким именем нет,
+и в проекте без установленного пакета запускала чужой код. Теперь у каждого случая
+каталога сказано, что отказ советует, и совет выполняется в том состоянии, которое
+его напечатало: сверяется код (включая «отказ ушёл» — тот же зов после совета должен
+ответить другим), а совет-форма без значений проверяется по справке (те ли команды и
+ключи). Совет, который выполнить нечем, назван с причиной: правка настроек, коммит,
+установка зависимости — за человеком, и это сказано там же, в каталоге. Новый совет
+в уже существующем отказе молча не пройдёт: совет вынимается из вывода по маркерам
+(«починка:», «создайте его:», «соберите её:»), и у него обязано быть объявление.
+
+**Волна 3 чистки пройдена** (`REFACTOR.md`): обвязка проверок одна на пакет
+(`tools/harness.js`), прогоны на чтение не повторяются, клон фикстуры держится на
+набор, а тяжёлый паритетный файл распался по предметам — и он, и команды CLI идут
+волной по ядрам. Проверок было 39 и все 39 сохранены (имена сверены), а новые
+добавлены только вместе с новым поведением страницы, подключения и разбора
+модулей, а последние — о том, что записанное в манифестах сходится с файлами
+эталонов, и о склейке кусков вывода процесса, и о дереве файлов, и о памяти
+выбора и ссылке на странице, семь — о настоящем сжатии и семь — о токенах (§«Метрика
+`min` умеет считать по-настоящему», §«Метрика `tok` считает токены настоящим
+словарём», четыре — о сверке с деревом и выборе пути для состояния (§«История с
+удалениями больше не тупик»), три — о точности по клетке (§«Точность числа»);
+всего 80.
+
+**Разбор модуля перестал стоить запуска Node на клетку** (`REFACTOR.md` R-5.4).
+Гард понимает модуль через `vm.SourceTextModule`, а он живёт только под
+`--experimental-vm-modules`: раньше отсюда и брался отдельный процесс на каждую
+клетку. Теперь модуль разбирает один рабочий поток на прогон: на синтетической
+истории с модулями (31 коммит, 3 файла, файл меняется каждым коммитом) `--write`
+**5,59 → 0,47 с**, на той же истории со скриптами — те же 0,39 с (скриптовый
+проект за поток не платит вовсе), а на проекте с одной изменённой клеткой —
+0,44 → 0,40 с. Цена не исчезла, а стала разовой: старт потока ≈ 54 мс вместо
+86 мс на каждую клетку, плюс разбор опирается на экспериментальный API (без него
+гард отступает к прежнему `node --check` — медленнее, но не мягче).
+Прогон подешевел втрое: `pnpm test` 15,7 → **5,6 с** (тогда в наборе было 39
+проверок), `pnpm run parity:live` 23,8 → **8,3 с**. Бюджет времени переснят с
+запасом на следующую проверку, а не под сегодняшнее число: набор стоит
+**23,4–29,9 с** при 124 проверках — в зависимости от загрузки машины: окна с
+загрузкой 18–70 несравнимы (в спокойном — 23,4–24,2 с, в занятых — 26,6–29,9 с;
+в среде без настроек git — 27,4 с, с `CI=1` — 29,9 с), и это свойство окна, а не
+набора: под той же загрузкой та же ревизия без нового сторожа идёт 24,4–26,3 с
+при 122 проверках. Вклад сторожа выпуска измерен **парным прогоном** с
+чередованием (124 → 122 проверки и обратно, два круга): **+2,0 и +2,2 с**, при этом
+сам он стоит 1,4 с собственным прогоном (`node --test test/changelog.test.js`: два
+запуска инструмента на фикстуре) и идёт параллельно прочим файлам.
+Числа разных окон несравнимы вовсе: тот же набор при 119 проверках шёл 25,5–25,7 с,
+хотя теперь проверок больше. Дороже всего в наборе — запуски инструмента: перебор
+режимов и правило `--json` в `test/cli.test.js` стоят по нескольку десятых секунды
+каждая, а разложение сторожа документации на четыре файла времени **не
+прибавило** — 23,2 с и до него, и после: обе новые проверки измерены отдельным
+прогоном, а не выведены из разброса. Из общего времени **+8,5 с** — десять проверок хука
+(`test/hook.test.js`: сам он идёт 17,9–18,5 с и становится самым долгим файлом
+набора, а та же ревизия без него — 15,8–16,6 с при 107 проверках). Цель не
+двигалась, и это решение, а не пропуск: цель тогда была одна — полный набор
+**≤ 28 с** (запас 2,3 с) — измеренное в неё укладывается, а поднимают цель по делу и с измерением,
+а не под занятую машину: интеграционные
+прогоны (клон, коммиты, слияние, отказы) дешевле не сделать, не ослабив проверку.
+`pnpm run parity:live` **≤ 15 с** (9,3 с в обеих средах). Замеры, машина и разброс —
+`REFACTOR.md` §5.
+
+**Прогонов два, и у каждого своя цель** (`REFACTOR.md` R-5.5). Цена проверки в этом
+наборе — не объём файла, а сколько раз файл запускает инструмент и git: запуск — это
+процесс Node, а клон фикстуры и сборка артефакта — сотни миллисекунд. Поэтому
+быстрый прогон собирает то, что доказывает по прочитанному (исходники, дерево,
+справка, эталонные числа на общей фикстуре), а полный добавляет то, что гоняет
+инструмент по многу раз на своих клонах, коммитит и ставит хуки; причина для каждого
+дорогого файла названа построчно в `tools/suites.js`, там же снимок стоимостей
+(перемерить — `pnpm run suites:measure`).
+
+| Прогон | Команда | Проверок | Цель |
+|---|---|---|---|
+| Быстрый — каждая правка | `pnpm test` | **57 из 131** | **≤ 10 с** |
+| Полный — выкладка и CI | `pnpm test:all` | **131** | **≤ 32 с** |
+
+Ни одна проверка не потеряна и не ослаблена: полный прогон запускает все 132 теми же
+файлами, а быстрый берёт их часть. Умолчание — полный: файл становится быстрым только
+явно и с причиной, поэтому новое дорогое не может тихо уехать в быстрый. Стерегут это
+двое, и по-разному: `test/suites.test.js` — объявление (полнота классификации,
+причины, потолок стоимости быстрого файла), а сам прогон (`tools/run-tests.js`) —
+замер: он печатает стоимость каждого файла своим запуском, складывает числа проверок
+и валится, если вышел за цель вдвое. Снимок стоимости проверяется только замером,
+и это его законное место: подделанная стоимость у быстрого файла объявление проходит,
+а прогон её ловит. Цель при этом не порог: занятое окно растягивает прогон, и
+прогон, не уложившийся в цель, говорит это словами («ЦЕЛЬ НЕ ДОСТИГНУТА»), а не
+показывает зелёную галку при 29 с. CI зовёт полный прогон дважды — обычной средой и
+без настроек машины. Числа и цели в этой таблице сверяются сторожем документации
+(`test/docs-numbers.test.js`), а не живут второй копией без присмотра.
+
+**Обещанное пакетом сведено к факту.** Список поставки называл четыре пути,
+которых в репозитории нет (`dist/`, `templates/`, `CHANGELOG.md`, `LICENSE`):
+теперь он обещает только существующее (шаблоны и `CHANGELOG.md` вернулись в список
+вместе с файлами, а не раньше их), а `pnpm run pack:check` проверяет это с двух
+сторон — в списке нет того, чего нет, и в тарболл не попадает то, чего список не
+обещает. Снятие обоих эталонов снова работает (`pnpm run parity`, `pnpm run
+fixture`) и больше не зависит ни от того, держит ли проект-потребитель свою копию
+инструмента, ни от настроек git на машине. Заодно поправлены два текста, которые
+это же обещали: подсказка `--init` (говорила «проверки едут вместе с пакетом», а
+сьют в пакет не входит) и умолчание `fixCommand` (называло несуществующее имя
+пакета `npx size-table --write`).
+
+**Проверки идут сами (шаг 6 плана, `.github/workflows/ci.yml`).** На каждый пуш и
+на каждый запрос правки один job проходит семь шагов теми же командами, что и у
+себя локально: строгий линтер, набор проверок, тот же набор в среде, где настроек
+машины нет вовсе (`GIT_CONFIG_GLOBAL=/dev/null`), работу из собранного тарболла,
+сверку с историей проекта-потребителя и воспроизводимость обоих эталонов.
+Секретов job не требует: история потребителя лежит в репозитории бандлом на той
+же ревизии, что записана в эталоне (`fixtures/live/`), а пересъём идёт во временный
+каталог и сверяется с закоммиченным — рабочее дерево остаётся чистым. Матрицы по
+версиям Node и публикаций нет намеренно: этот проход про контроль.
+
+Первым же прогоном CI окупился: шаг живого паритета упал не на расхождении чисел,
+а на самой проверке — вывод процессов собирался как строка, и многобайтовый символ,
+разорванный между кусками чтения, превращался в два символа-заменителя (местные
+прогоны этого не показывали: границы кусков зависят от того, как ядро вернуло
+чтение). Дефект починен, сторож — `test/runner.test.js` (`WORKLOG.md` §21).
+
+Второй прогон нашёл ещё два дефекта, и оба — про git по обе стороны границы
+вызова. Шаг воспроизводимости эталонов сверял бандл истории **побайтово**, а
+упаковку пишет git: её байты зависят от версии, и проверка была зелёной на одной
+машине и красной на другой (фикстура это и в README утверждает). Теперь у бандла
+сверяется содержимое — ветки, верхушка и число коммитов, — а побайтово только то,
+что пишем мы сами. Второй: бандл живой истории лежал **без `HEAD`**, и клон сам
+решает, какую ветку выложить, — разные версии git решают по-разному (`hint: Using
+'master' …`). Бандл пересобран с `HEAD`, `check:standards` это требует, а отказ
+инструмента печатается целиком, а не первой строкой (`WORKLOG.md` §22).
+
+**Страница отчёта выглядит и ведёт себя как инструмент** (`REFACTOR.md` R-2.2):
+один набор стилей таблицы на оба вывода (`src/table.css`) — странице достались
+липкие шапка и колонка коммита, которые раньше были только у статического
+артефакта, и она больше не уезжает вбок в узком окне (до правки — 1518px при
+окне 620). Добавились легенда с цветами дельт, состояния «нечего показать»
+(сняты все метрики или все файлы) и переключатели, доступные с клавиатуры. Цвет
+deльт задан один раз и по артефакту: рост зелёный, спад красный — смена это две
+строки в `src/table.css` плюс пересборка эталона артефакта, больше цвета нигде нет.
+
+**Левая панель страницы — дерево файлов** (`REFACTOR.md` R-2.4). Папки берутся из
+тех же путей, что показаны в подписи файла (ни одного перечисления руками), у
+папки три состояния — все её файлы включены, часть, ни одного, — и переключатель
+папки ведёт за собой всё поддерево; рядом стоит число файлов. Своего состояния у
+папки и у быстрой кнопки категории нет: обе переставляют галочки файлов, поэтому
+дерево, кнопки и таблица не могут разойтись. Список файлов длиной больше трети
+экрана прокручивается внутри панели, а не выталкивает таблицу: на живой истории
+(91 строка × 25 файлов) панель занимает 429 px, таблица начинается на 544-м.
+Стрежет это проверка на числах таблицы, а не на разметке: выключение папки убирает
+ровно её колонки и ровно её объём из итога (`test/contract.test.js`). Проверено в
+настоящем Chrome: 9 папок до трёх уровней вложенности (`.github/workflows`,
+`tests/golden`), 25 файлов, ни одного внешнего запроса (сеть — только сам файл),
+ни одной ошибки в консоли, `docs/6` после выключения одного своего файла показала
+третье состояние, а после выключения целиком — 52 колонки → 40.
+
+**Панель помнит выбор читателя** (`REFACTOR.md` R-2.5). Запись хранится в памяти
+браузера, и она привязана к «паспорту отчёта» — имя инструмента, схема данных,
+путь артефакта, заголовок и метки колонок; в ключ входит отпечаток паспорта,
+поэтому чужие отчёты живут порознь и не видят выбора друг друга (в браузере все
+страницы `file://` делят одну память, так что это не мелочь). Внутри записи выбор
+лежит **по именам** — файл путём, метрика ключом, — и хранится только выключенное:
+колонка, перенаправленная на другое, или метрика, убранная из настроек, просто
+ничего не значит, появившееся остаётся включённым, а «включил всё обратно»
+возвращает страницу к умолчанию и стирает запись. Первому читателю (и тому, чья
+запись испорчена или устарела) достаётся именно умолчание — состояние на числа и
+разметку не влияет. Проверено перезаходом в настоящем Chrome с диска, без сети:
+после выключения метрики и одного файла следующий заход даёт те же **25 колонок
+вместо 52** и тот же итог **994 335 вместо 1 133 362**; два отчёта в одном браузере
+держат по своей записи (`size-report:4684b2b2` и `size-report:5dcd0db1`), и выбор
+одного не трогает другой.
+
+**Ту же выборку отдают ссылкой** (`REFACTOR.md` R-2.6). Адрес страницы — это и есть
+ссылка: та же запись, что ложится в память браузера, ложится и в якорь
+(`#size-report=…`), поэтому отправитель просто копирует адрес, а получатель видит
+его выбор без единого действия. Ссылка старше памяти: она — явный выбор
+отправителя, а память читателя она не подменяет, пока тот сам чего-нибудь не
+поменяет. Чужой или испорченный адрес не применяется — и не молчит: над таблицей
+появляется строка с причиной («ссылка собрана в другом отчёте» / «выбор в адресе
+нечитаем»), вид остаётся читательским, а присланный адрес не переписывается; о
+именах, которых в отчёте нет, сообщается числом, они пропускаются, остальное
+применяется. Ссылка работает и когда отчёт уже открыт: браузер на смену якоря
+документ не перезагружает, поэтому страница слушает адрес сама (без этого ссылка
+срабатывала бы только в новой вкладке — этот разрыв нашёлся в браузерной
+проверке, а не в тестах). Проверено на живом отчёте в Chrome с диска: получатель с
+пустой памятью по ссылке видит те же **25 колонок и тот же итог 994 335**, что и
+отправитель; чужой адрес оставляет 52 колонки и 1 133 362 и объясняет отказ; на
+уже открытой странице ссылка меняет вид с 52 колонок на 25, а консоль остаётся
+пустой. Ни одного обращения в сеть в странице нет — это отдельное утверждение
+проверки, а не обещание.
+
+**Метрика `min` умеет считать по-настоящему** (шаг 3 плана, срез 1). Способ
+выбирается в настройках: `"minify": {"engine": "esbuild"}` — настоящее сжатие
+(JS/TS/CSS) необязательной зависимостью, `"engine": "strip"` — прежнее снятие
+комментариев и отступов; умолчание не менялось, потому что под ним сняты оба
+замороженных эталона. На фикстуре сжатие меньше упрощения в **44 клетках и ни разу
+не больше**: `src/code.js` **276 → 185 Б**, `src/style.css` **55 → 43 Б**, по фикстуре
+**−1 372 Б**. Цена сжатия названа, а не спрятана: на живой истории (95 строк ×
+27 колонок) прогон стал **1,48 → 1,71 с** — это запуск минификатора и разбор тех
+файлов, которые он берёт. JSON минифицируется разбором и потому
+остаётся точным, а форматы, которых минификатор не берёт, честно названы в подписи
+метрики вместе с теми, которые он берёт. Точность объявлена дважды, и это не два
+ответа на один вопрос: подпись метрики говорит про **худшее в колонке** (один
+формат без минификатора делает метрику приближённой целиком, а не прячется за
+«точное» соседа), а каждая клетка — про своё число, и приближённая помечена
+пунктиром с подписью способа. Худшее берётся у клеток, а не у названия способа:
+отчёт из одного JSON точен и под снятием балласта — разбор теряет только
+незначащие пробелы, короче его не сделает никто, — и подпись так и говорит.
+Оба ответа считаются одним правилом (`pointExact` в
+`src/metrics.js`), поэтому разойтись не могут. Минификатора нет (установка без необязательных
+зависимостей, платформа без него) — метрика отступает к упрощению, способ говорит
+об этом словами, а прогон отдаёт **код 4**, а не молчание: числа при этом те же, что
+у прежнего способа, — побайтово со эталоном. Черновик `--init` ведёт новые проекты
+сразу на сжатие; цена названа прямо в его подсказке. Файл, который минификатор не
+разобрал (разметка в `.js`, чужой синтаксис), — отказ кодом 2 с причиной от него
+самого и двумя готовыми выходами.
+
+**Метрика `tok` считает токены настоящим словарём** (шаг 4 плана, срез 1). Токены —
+третье измерение отчёта: вес файла для языковой модели. Словарь выбирается в
+настройках (`"tokens": {"family": "openai", "encoding": "o200k_base"}`), и
+кодировка — часть числа, а не подробность: на фикстуре `src/code.js` это **168
+токенов** в `o200k_base` и **196** в `cl100k_base`, поэтому кодировка называется
+рядом с семейством, а способ метрики цитирует ровно ту, что посчитана. Токены —
+не байты и не сжатие, и расхождение видно, а не заглажено: та же клетка — **735 Б**
+`raw`, **276 Б** упрощением, **185 Б** настоящим сжатием и **168** токенов; байт на
+токен отличается по файлам в **2,5 раза** (от 2,56 у `package.json` до 6,30 у
+`crlf.txt`), то есть считается текст, а не отношение. Семейство в этой версии одно —
+`openai`: у остальных нет словаря, который можно было бы назвать их собственным, а
+считать чужим и называть это семейством значило бы обещать то, чего нет.
+Переключателя словаря на странице нет намеренно: страница получает готовые числа и
+сама не считает ничего, а посчитать токены другим словарём ей нечем. Сосчитать все
+семейства на каждый прогон — это платить временем за числа, о которых читатель,
+может быть, и не спросит, поэтому выбор семейства и кодировки живёт там, где стоит
+времени (в настройках запуска), а страница его **называет**: способ каждой метрики
+виден под переключателями текстом, а не только во всплывающей строке (решение
+плана §4.8.4 отменено осознанно — `PLAN.md`, шаг 4).
+Форматы без текста (картинка, шрифт, архив) названы в подписи метрики вместе с
+причиной: у них число идёт по байтам, и по тому же правилу помечена клетка такого
+файла, а подпись метрики берёт худшее в колонке — двум ответам разойтись нечем.
+Словаря нет (установка без необязательных зависимостей, платформа без него) — счёт
+идёт оценкой по длине с названным коэффициентом, а прогон отдаёт **код 4**; числа
+при этом те же, что у прежнего отчёта без токенов, а сам шов проверяется
+окружением `SIZE_REPORT_NO_OPTIONAL`. Прогон этим платит временем, и это честная
+цена словаря, а не разбор: таблицы словаря читаются **0,3 с на процесс**, а на
+живой истории (95 строк × 27 колонок, 1,23 МБ текста) тот же отчёт идёт
+**1,55 → 6,35 с** — умножается именно сбор истории, а не таблица: токенов в
+«сейчас» — **303 705**, то есть 4,05 Б на токен. Отсюда и цена набора проверок:
+**7,3–7,9 → 10,4 с** при 66 → 73 проверках (запас и новый бюджет — ниже). Черновик
+`--init` ведёт новые проекты сразу на токены.
+
+**Волна 0 чистки пройдена** (`REFACTOR.md`): у отказов командной строки появились
+коды выхода и справка вместо стека, `--help` отвечает, `--page` и `--write`
+создают недостающий каталог, подсказка в отказе ведёт к работающей команде, а
+черновик `--init` больше не предлагает колонкой саму таблицу — иначе первая же
+проверка настроек его отвергала.
+
+**Появились две команды: полнота и объяснение** (шаг 5 плана). `size check`
+отвечает, всё ли в истории попало в отчёт: каждый путь, тронутый коммитами,
+обязан быть колонкой или объявленным исключением, а непонятый путь — это код 1,
+путь, коммит, который его завёл, и готовая починка. Тем же ответом идут сводка по
+выпавшим коммитам (сколько и почему) и списки их sha — то есть «какая часть
+истории покрыта». `size explain <коммит>` отвечает про один коммит — назвать его
+можно и именем ревизии (`HEAD`, ветка, тег, `HEAD~1`), и sha, и началом sha:
+строка есть (и которая) либо причина, почему её нет, — тронут только отчёт, числа не сдвинулись
+при тронутых файлах колонок, коммит мимо колонок, слияние скрыто `rows.merges`.
+Обе берут причину у того же прохода, что и отчёты, а улики — из списка изменённых
+путей коммита: чего в истории нет, о том молчание вместо догадки. Полнота — из требований (§4.2: «ни одно изменение не
+просочилось мимо отчёта»), и она же заменяет контроль
+«артефакт ↔ история»: отчёт можно не хранить в git. Смысл `skip` в настройках от
+этого не изменился, но **значение расширилось**: это не только «пути, которые
+колонками быть не могут», но и объявленные исключения полноты — тот же список, и
+чеканить второй инструмент не стал. Цена названа: `check` — это проход по истории,
+как и любой отчёт (**1,5 с** на живой истории), а набор проверок подорожал на
+тринадцать запусков инструмента (бюджет — ниже). К ним добавился `size doctor` —
+диагностика одним ответом (ниже, в разделе про проверки).
+
+**Отчёт обновляется сам** (последний пункт шага 5 плана). `size install-hook`
+ставит два хука — `post-commit` и `post-merge` (`post-commit` при `git merge` не
+выполняется вовсе, поэтому одного файла мало), — и после каждого коммита и слияния
+отчёт пересобирается, а лежащий в git — ложится **отдельным коммитом**: ручного шага
+«код, потом таблица» больше нет. Коммит отчёта собирается плумбингом git
+(`commit-tree`): в него физически не могут попасть ни индекс, ни чужая
+незакоммиченная работа, и зацикливание невозможно по устройству, а не по флагу в
+окружении. Отказ инструмента коммит не роняет — причина печатается строкой и
+видна в `size doctor`.
+
+Перенос, доработка и оформление в пакет расписаны в `PLAN.md` по шагам, с
+приёмкой каждого.
+
+## Что в репозитории
+
+| Файл | Роль |
+|---|---|
+| `PLAN.md` | **Главный документ:** инвентаризация, границы, инварианты, архитектура, семь шагов переноса, приёмка, риски, открытые вопросы |
+| `docs/requirements.md` | Требования заказчика: что и зачем |
+| `docs/module-design.md` | Архитектурный проект выноса: как устроен модуль |
+| `WORKLOG.md` | Журнал запросов и сделанного |
+| `BLOCKERS.md` | Открытые блокеры и известные пробелы (обход обязан держаться проверкой) |
+| `REFACTOR.md` | Поканальный план чистки: объём кода, потом скорость; границы и чем доказывается, что поведение не изменилось |
+| `CHANGELOG.md` | История выпусков и, у каждого выпуска, раздел «Что изменится в числах»: у кого числа поедут и почему |
+| `tools/parity-freeze.js` | Снимает эталон паритета (`pnpm run parity`): замороженной копией, на ревизии проекта из манифеста — `--json`, конфиг, хеш артефакта, хеш инструмента |
+| `tools/make-fixture.js` | Собирает синтетическую фикстуру (`pnpm run fixture`): детерминированную историю с ловушками плюс эталонные числа |
+| `tools/parity-live.js` | Сверяет движок с живым проектом на клоне: числа и артефакт (`pnpm run parity:live`) |
+| `tools/pack-check.js` | Собирает тарболл и проверяет, что из него всё работает: все исходники доехали, числа, артефакт и страница — как из репозитория (`pnpm run pack:check`) |
+| `tools/check-standards.js` | Проверяет, что оба эталона воспроизводятся: пересъём идёт в никуда и сверяется с закоммиченным (наши файлы — побайтово, бандл — по содержимому) и что бандл живой истории несёт `HEAD` (`pnpm run check:standards`) |
+| `.github/workflows/ci.yml` | CI: семь шагов на каждый пуш и запрос правки — те же команды, что локально, без секретов и матриц |
+| `templates/` | То, что проект берёт как есть: `size-report.config.json` (черновик настроек), `ci.yml` (описание проверки) и `README.md` (куда что кладётся и что в них менять); едут в поставке и стерегутся `pack:check` и `test/templates.test.js` |
+| `fixtures/parity/` | Эталон с `safe-resets` на коммите `bd6ef9d`: 95 строк × 27 колонок. Копия реализации, которой он снят, в дереве не лежит — её байты живут в истории и берутся оттуда по требованию (`REFACTOR.md` R-1.5) |
+| `fixtures/synthetic/` | Бандл фикстуры на 16 коммитов, её конфиг, эталонные числа и хеш артефакта |
+| `fixtures/live/history.bundle`, `fixtures/live/README.md` | История проекта-потребителя на ревизии эталона `bd6ef9d` и записка о том, какую ревизию бандл несёт и почему он лежит в репозитории: живая сверка работает без доступа к приватному проекту |
+| `bin/size.js` | Команда `size`: то, что ставит пакет (`package.json` → `bin`); сама ничего не считает, только зовёт точку входа |
+| `LICENSE` | MIT: условия лицензии едут в поставке вместе с пакетом |
+| `.gitignore`, `pnpm-lock.yaml` | Что в репозиторий не идёт; lock-файл pnpm, а версия менеджера — в поле `packageManager` (оттуда её берёт CI) |
+| `src/size-table.js` | Точка входа пакета: только реэкспорт публичного API (58 имён), ни одного расчёта |
+| `src/derived.js` | Общий расчёт отчёта: итоги, дельты, клетка, подпись коммита — одно место на артефакт и страницу |
+| `src/css.js` | Чтение оформления с диска: какие наборы стилей есть и какая у них роль |
+| `src/table.css` | Общая часть таблицы: геометрия клеток, липкие шапка и колонка, цвет дельт — одна на артефакт и страницу |
+| `src/artifact.css` | Оформление статического артефакта сверх общей части |
+| `src/page/app.css` | Оформление страницы сверх общей части: панель с деревом файлов, состояния пустоты, узкое окно |
+| `src/page/app.js` | Программа страницы: дерево файлов, разметка, состояние галочек, память выбора и ссылка; вклеивается в собранную страницу |
+| `src/page/build.js` | Сборка страницы: данные, оформление и программа в одном файле без внешних ссылок |
+| `src/git.js` | Единственная граница вызова git: закрепления настроек, блобы пачкой, история, сверка с диском |
+| `src/strip.js` | Снятие балласта: стрипперы комментариев и отступов и правила, какая форма к какому файлу, гард компиляции |
+| `src/parse.js` | Разбор модуля: рабочий поток на прогон и отступление к `node --check`, способ разбора последнего модуля |
+| `src/parse-worker.js` | Сам разбор внутри потока: разбирает текст без исполнения, сообщает, что модулей vm в Node нет |
+| `src/metrics.js` | Реестр метрик: что измеряется, нужен ли текст и насколько честна цифра; описание метрики для читателя — в одном месте |
+| `src/minify.js` | Настоящий минификатор: необязательная зависимость, загружается один раз и не роняет прогон, если её нет |
+| `src/tokens.js` | Токены: словарь по семейству и кодировке, оценка по длине как запасной счёт, форматы без текста |
+| `src/optional.js` | Общее устройство необязательных зависимостей (минификатор и словарь): ленивая загрузка, версия пакета, шов отсутствия |
+| `src/history.js` | Обход истории: измерение по коммитам, сдвиг чисел, сборка, сверка с деревом и причина пропуска у каждого выпавшего коммита |
+| `src/check.js` | Полнота покрытия (`size check`): настройки, история, пути, датчики — что прошло мимо колонок и чем это чинится |
+| `src/explain.js` | Объяснение пропущенной строки (`size explain <коммит>`): причина, улики и готовая починка |
+| `src/doctor.js` | Диагностика одним ответом (`size doctor`): окружение, зависимости, настройки, покрытие, состояние хука — сборкой из существующих кусков |
+| `src/hook.js` | Хуки автообновления (`install-hook` / `uninstall-hook` / `hook-run`): установка и снятие, коммит только отчёта, замок и запись о запуске |
+| `src/artifact.js` | Артефакт на диске: единственное место, где отчёт превращается в файл (им пользуются и `--write`, и хук) |
+| `src/journal.js` | Журнал и ссылки: к какому разделу относится коммит и куда ведёт описание |
+| `src/data.js` | Категории файлов и контракт со страницей (`--data`) |
+| `src/render.js` | Статический артефакт: клетки, таблица, примечание (стили — в `src/css.js`) |
+| `src/config.js` | Настройки проекта-потребителя: умолчания, чтение, проверка |
+| `src/locales.js`, `src/refusal.js`, `src/tool.js` | Тексты отчёта; коды выхода и справка; имя и версия пакета |
+| `src/cli.js` | Режимы командной строки и разбор ключей; главный файл пакета |
+| `test/api.test.js` | Публичный API пакета: список имён заморожен, разбиение не имеет права его менять |
+| `eslint.config.js` | Правила оформления: те же, что у проекта-потребителя, плюс запрет склейки операторов в строке (`pnpm run lint`, `pnpm run lint:strict`) |
+| `tools/harness.js` | Обвязка проверок: пути, клоны фикстуры (в том числе общий на набор и с CRLF), запуск инструмента, разбор отказов, хеши |
+| `tools/suites.js` | Разделение набора: какие файлы идут в быстрый прогон (с причиной и снимком стоимости), почему каждый дорогой — в полном, и цели обоих прогонов |
+| `tools/run-tests.js` | Прогон набора (`pnpm test`, `pnpm test:all`, `pnpm run suites:measure`): стоимость каждого файла своим замером, сверка числа проверок, граница бюджета |
+| `tools/docs-facts.js` | Чтение фактов из документации — один слой на четыре проверки сторожа: что документ называет (пути, зовы, адреса разделов) против того, что есть в репозитории |
+| `tools/refusals.js` | Каталог отказов: по строке на каждый — причина, код выхода, обязательные фразы вывода, **что отказ советует** (`advice`: `run` — команда, `template` — форма с подстановкой, `manual` — действие человека с причиной, `coveredBy` — отдан другой проверке), а для непроверяемого — почему; карты мест отказа (`SITES`, `PRINTED`) держат числа, чтобы новый отказ не появился молча, а маркеры совета — чтобы не появился молча новый совет |
+| `test/parity.test.js` | Паритет движка с эталоном: числа, артефакт, локаль |
+| `test/frozen.test.js` | Замороженная копия: та ли это ревизия, с которой снят эталон, и воспроизводит ли она его |
+| `test/environment.test.js` | Герметичность: вывод не зависит от настроек git машины и локали |
+| `test/crlf.test.js` | Выкладка с CRLF (`core.autocrlf`) не мешает сверке |
+| `test/disk.test.js` | Сверка с рабочим деревом: правка только на диске, три вида потери (правка, создание, удаление — все мутацией), файл, удалённый до HEAD, и переименование внутри псевдонимов — не потеря (`BLOCKERS.md` §B3, §N8) |
+| `test/cli.test.js`, `test/cli-paths.test.js` | Отказы командной строки: справка, настройки, коды выхода — и куда инструмент пишет |
+| `test/refusals.test.js` | Отказы исполняются: каждый вызван прогоном, сверены код выхода и обещанные фразы (свои клоны — для чужого хука, обрезанной истории и ветки мимо отчёта), и **совет выполняется** — команда даёт обещанный код, не падает стеком, а где объявлено «отказ ушёл», тот же зов после неё отвечает другим |
+| `test/refusals-catalog.test.js` | Сторож каталога отказов: у каждого места отказа в исходниках есть пункт, у каждого пункта — объявленный совет, а отказы, отданные другой проверке, ею в самом деле утверждаются (названные файл и строка проверяются) |
+| `test/contract.test.js` | Контракт данных и страница: числа против эталона, производные против чисел артефакта, дерево файлов против путей, память выбора и ссылка против перезахода, чужого отчёта и чужого адреса, пометки приближения против подписи метрики |
+| `test/module.test.js` | Модуль в расширении `.js`: измеряется без правок настроек; гард стриппера жив (доказано мутацией) и не обвиняет невиновного |
+| `test/guard.test.js` | Разбор модуля: идёт потоком, оба пути дают один вердикт, отступление работает без файла потока, сотни разборов дешевле запуска |
+| `test/runner.test.js` | Чтение вывода процесса: куски склеиваются буферами, а не приклеиваются к строке — многобайтовый символ на границе кусков не превращается в два символа-заменителя |
+| `test/git-pins.test.js` | Сторож границы git: прямых вызовов git без общего списка закреплений нет, и незакреплённое чтение показывается свидетелем (путь кавычками) |
+| `test/docs-paths.test.js`, `test/docs-commands.test.js`, `test/docs-numbers.test.js`, `test/docs-pin.test.js` | Сторож документации, по файлу на обещание: пути и таблица файлов; зовы, причины отказа и адреса разделов; числа проверок и цели по времени; пин в примере установки |
+| `test/changelog.test.js` | Сторож выпуска: версия в `CHANGELOG.md` — версия манифеста, а таблица «что изменится в числах» — это замер на фикстуре, сверенный с живым прогоном |
+| `test/suites.test.js` | Сторож разделения набора: полнота классификации (быстрый — явно, полный — с причиной), потолок стоимости быстрого файла, что быстрый прогон остаётся частью набора |
+| `test/check.test.js` | Полнота и объяснение на настоящих коммитах фикстуры: непокрытый путь, «только отчёт», «число не сдвинулось», «мимо колонок», слияние — и что починка настроек не двигает числа |
+| `test/doctor.test.js` | Диагностика на пяти состояниях проекта: без настроек (2), полное покрытие (0), неполное (1), обрезанная история (3), нет датчика (4) — и блок покрытия равен ответу `size check`, а не считается вторым разом |
+| `test/hook.test.js` | Хуки на свежем клоне: ставятся только командой, дают отдельный коммит отчёта (в том числе после слияния), повторный запуск молчит, чужая работа и индекс не тронуты, в CI и при отказе инструмента ничего не делают, снятие возвращает проект к прежнему |
+| `test/templates.test.js` | Шаблоны: черновик настроек проходит проверку инструмента и собирает настоящий отчёт; описание проверки разбирается и зовёт только существующие команды и ключи |
+| `test/minify.test.js`, `test/tokens.test.js` | Настоящее сжатие и токены: числа против упрощения, кодировка как часть числа, честность подписи, работа без необязательной зависимости (код 4) и шов `SIZE_REPORT_NO_OPTIONAL` |
+| `package.json` | Манифест пакета: имя `@vernikr/size-report`, версия `1.1.1`, список поставки — только существующее |
+
+Оба каталога эталонов снимаются заново теми же инструментами: `pnpm run parity` и
+`pnpm run fixture` дают те же файлы. Побайтово сверяется наше — конфиг, эталонные
+числа, хеш артефакта, описание; у бандла истории сверяется содержимое (ветки,
+верхушка, число коммитов), потому что упаковку пишет git и её байты зависят от его
+версии. Обе стороны пары закреплены — инструмент это замороженная копия реализации,
+чьи байты лежат в истории (`fixtures/legacy/size-table.cjs`, `REFACTOR.md` R-1.5) и
+сверяются с записью о происхождении эталона, а ревизия проекта берётся из манифеста
+(`--at` сдвигает её осознанно), окружение снятия задано (`core.quotePath=false`).
+Без закрепления окружения эталон снимается другими числами: на машине с настройками
+git по умолчанию фикстура с не-английским именем файла теряет строку. Проверено
+тремя прогонами: повтор даёт те же байты и прогон без настроек машины
+(`GIT_CONFIG_GLOBAL=/dev/null`) — тоже. Сходимость записанного в манифестах с
+файлами стережёт `test/frozen.test.js`.
+
+## Чего ещё нет
+
+```text
+dist/app.js        пре-собранная программа отчёта для публикации
+size init/measure  командами вместо флагов: сейчас командами стали только check, explain, doctor и хук
+блок для агентов   инструкция агенту проекта: требования её не просят, поэтому в шаблонах её нет
+минификация HTML   минификатор разметки: пока HTML считается упрощением (шаг 3)
+JSX и TSX          выход зависит от настройки jsx самого проекта — упрощение (шаг 3)
+семейства токенов  кроме openai: у остальных нет своего словаря — считали бы чужим (шаг 4)
+```
+
+Швы между модулями проходят по границам данных: сверху — то, что читает git и
+файловую систему (`git`, `strip`, `metrics`, `history`), ниже — то, что работает на
+уже собранных значениях (`data`, `render`, `page`), а настройки, тексты и отказ —
+по краям, потому что их знает любой и они не знают никого. Оба отчёта считаются на
+сборке: страница получает исходники общего расчёта и своей программы вклеенными
+(`src/derived.js`, `src/page/app.js`), потому что открывается она с диска, без
+сервера и без сети. Остальное — по шагам 2–6 (`PLAN.md` §5).
+
+## Как подключить к своему проекту
+
+Инструкция проверена покомандно на свежем проекте (три коммита, ESM в `src/`,
+`pnpm`): ниже — ровно те команды, которые работают сегодня. Всё, что сегодня
+**не** работает, названо здесь же и с причиной, чтобы это не искали опытом;
+каждый такой случай — отдельный пункт `REFACTOR.md`.
+
+Эта же инструкция — рецепт для шага 5 (`PLAN.md`): интеграция в проект-потребитель
+идёт по ней, а не по памяти.
+
+Нужны: **git-репозиторий с историей** (хотя бы один коммит — таблица строится по
+коммитам) и **Node ≥ 20.19** (`engines` пакета).
+
+### 1. Установка
+
+```bash
+pnpm add -D github:vernikr/size-report#v1.1.1
+```
+
+`npm i -D` и `yarn add -D` принимают ту же ссылку. **В npm пакет не опубликован**,
+поэтому `pnpm add -D @vernikr/size-report` не сработает. Репозиторий публичный, и
+учётных данных установка не требует: `github:` pnpm разрешает в архив
+`codeload.github.com` и тянет его по HTTPS.
+
+Без сети (или если тянуть из codeload нечем) — тарболл: `pnpm pack` в клоне
+пакета, затем `pnpm add -D ./vernikr-size-report-1.1.1.tgz`.
+
+**Почему тег, а не sha.** Короткий sha pnpm разрешает только через видимые рефы, а
+`git ls-remote` отдаёт одни верхушки веток: пока ревизия — верхушка, короткий sha
+работает, а как только ветка ушла вперёд, установка падает с `Could not resolve
+<sha> to a commit`. Это не рассуждение, а проба: короткий пин `6530237` ставился,
+пока `main` стоял на нём, и перестал — на следующем же коммите, а тот же sha
+целиком поставился. Имя ветки (`#main`) или тег принимаются оба, но ветка —
+движущаяся цель, а тег постоянен: этот выпуск стоит на теге `v1.1.1`, он же и в
+примере (сорок знаков тоже годятся, но их придётся брать глазами из истории).
+
+Ревизия в примере — не украшение, а часть утверждения: она закреплена за тем, что
+описано ниже. Пин старше подкоманд (`check`, `doctor`, `explain`, `install-hook`)
+означал бы, что текст учит командам, которых в установленной ревизии нет, а
+лишнее слово там не отвергается, а молча пропускается — то есть вместо отказа
+человек получил бы ноль и решил, что всё в порядке. Поэтому пин берётся не «какой был под рукой», а
+ревизией, в которой есть всё названное ниже — включая отказы на незнакомое слово. За этим следит сторож документации (`test/docs-pin.test.js`): пин обязан вести
+на ревизию этого репозитория, и все названные в тексте команды обязаны быть в её
+справке.
+
+Репозиторий пакета **публичный** (приватным был до 2026-09-14), и это ровно то,
+что упрощает установку: ни ключа разработчика, ни шага в CI с доступом. Проверено
+прогоном в пустом проекте, где у git не было ни глобальных настроек, ни
+помощника учётных данных (`GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
+GIT_SSH_COMMAND=false`): установка 3,4 с, дальше `size --write` и `size` работают
+(`WORKLOG.md` §44). Прежнее требование было ценой приватности: локально — ключ, а
+в CI — read-only deploy key перед `pnpm install` (то самое первое подключение,
+`WORKLOG.md` §18); шаг с ключом из шаблона ушёл вместе с приватностью. Что
+остаётся на потом — публикация в npm (`PLAN.md` §8.4), и там есть цена: имя
+`size-report` в npm занято чужим пакетом (2017 год, три версии), поэтому
+публикация — это имя в области владельца (`@vernikr/size-report`), а не выкладка
+под прежним именем; что затронуло переименование — `PLAN.md` §10.
+
+### 2. Черновик настроек
+
+```bash
+pnpm exec size --init      # создаёт size-table.config.json
+```
+
+Черновик собирается по самому проекту: колонки — крупнейшие файлы каждого
+расширения, журнал — по знакомым именам (`WORKLOG.md`, `CHANGELOG.md`, …), вывод —
+в `docs/`, если он есть, `fixCommand` — под ваш менеджер пакетов. Он же печатает
+следующие три шага. Черновик ведёт метрику `min` на настоящее сжатие
+(`"minify": {"engine": "esbuild"}`) и сразу включает метрику `tok`
+(`"tokens": {"family": "openai", "encoding": "o200k_base"}`): и минификатор, и
+словарь едут необязательными зависимостями и ставятся обычной установкой, а без
+них инструмент работает и сам скажет об этом (код 4) — правки настроек не
+требуются.
+
+> Subкоманды `size init` пока нет — CLI знает только флаги (`--init`, `--write`,
+> `--page`, `--data`, `--json`, без флага — проверка); полный список даёт `size --help`.
+> Subкоманды — шаг 5 плана (`REFACTOR.md` R-4.5).
+
+### 3. Что правится в конфиге
+
+Черновик знает про проект только размеры файлов — какие колонки важны, знает
+человек. Чаще всего правят:
+
+| Ключ | Что это |
+|---|---|
+| `columns` | колонки таблицы: `{label, paths: [...]}`; пути в одной колонке складываются (например, `src` целиком), `label` — то, что увидит человек |
+| `metrics` | из чего состоит число: `raw` (размер объекта git), `min` (минифицированная форма — какая именно, решает `minify.engine`), `tok` (токены), `gzip` |
+| `tokens.family`, `tokens.encoding` | словарь для `tok`: семейство (`openai`) и кодировка (`o200k_base` или `cl100k_base`) — кодировка меняет число, поэтому она и в настройках, и в подписи метрики |
+| `minify.engine` | чем считается `min`: `strip` (комментарии и отступы, точность не обещается) или `esbuild` (настоящее сжатие; форматы без минификатора — упрощение, и это видно в подписи метрики) |
+| `output` | файл таблицы (по черновику — `docs/size-table.html`) |
+| `journal` | где искать разделы журнала, на которые ссылаются строки |
+| `links.commitUrl` | шаблон ссылки на коммит, например `https://github.com/org/repo/commit/{sha}` |
+| `skip` | пути, которые колонками быть не могут |
+| `fixCommand` | команда, которую цитирует подпись отчёта и подсказывает отказ; в черновике уже ваша |
+| `minify.guard` | расширения, где результат стриппера проверяется разбором; модуль в `.js` гард понимает сам, трогать его не нужно |
+| `hooks.enabled` | выключатель хука автообновления (`false` — хук остаётся на месте, но молчит; убирается он только `size uninstall-hook`) |
+
+Остальные ключи и умолчания — `src/config.js` (`DEFAULT_CONFIG`).
+
+### 4. Скрипты и первый отчёт
+
+```jsonc
+// package.json
+"scripts": { "sizes": "size --write", "test:sizes": "size" }
+```
+
+```bash
+pnpm run sizes            # → docs/size-table.html — таблица коммитов и чисел
+pnpm exec size --page     # → docs/size-report.html — интерактивная страница
+```
+
+Оба отчёта — самодостаточные файлы: открываются двойным щелчком, без сервера и
+без сети (внешних ссылок в них нет вовсе, данные и программа вклеены). Числа
+между ними одни и те же — страница считает производные (дельты, итоги, фильтры)
+из тех же абсолютных значений тем же кодом, что и таблица.
+
+**Порядок правок:** код → `pnpm run sizes` → коммит с одной таблицей. Таблица
+обновляется **отдельным коммитом**, потому что строка коммита не может попасть в
+саму таблицу: обновили её вместе с кодом — инструмент предупредит
+(`! таблицу обновляли вместе с кодом: <sha>`) и назовёт коммит, который выпал.
+Проверка `size` собирает таблицу заново и сверяет с файлом на диске, поэтому она
+же ловит и забытую пересборку. Убрать отчёт из git совсем — шаг 5 плана
+(`PLAN.md` §5).
+
+### 5. Проверка в CI и перед коммитом
+
+```bash
+pnpm run test:sizes       # 0 — таблица сходится с историей
+pnpm exec size check      # 0 — ни одно изменение не прошло мимо колонок
+pnpm exec size doctor     # 0 — делать нечего; иначе первый по важности код
+```
+
+`size check` отвечает на другой вопрос, чем сама команда `size`: та говорит
+«таблица совпадает с историей», а эта — «история вся посчитана»: каждый путь,
+который трогали коммиты, должен быть либо колонкой, либо объявленным исключением
+(`skip` и сам файл отчёта), иначе это **код 1** со списком путей, коммитом,
+который путь завёл, и командой починки. Отчёт при этом не обязан лежать в git —
+полнота и есть та проверка, которой заменяют «артефакт ↔ история».
+Если сомнение вызывает один коммит, `pnpm exec size explain <коммит>` объяснит,
+почему строки нет: тронут только отчёт, числа не сдвинулись, коммит мимо колонок
+или слияние скрыто настройкой — с уликами и починкой, где она есть. Коммит можно
+назвать так, как его зовёт git: `HEAD`, `HEAD~1`, имя ветки или тега, полный sha
+или его начало. Если имя ведёт на коммит вне истории отчёта (другая ветка),
+инструмент скажет именно это и назовёт его sha — а не «нет такого коммита».
+
+`size doctor` собирает всю диагностику в один ответ: окружение и его влияние на
+числа (настройки машины на числа не влияют — движок закрепляет их на границе
+вызова), состояние необязательных зависимостей и что оно значит для точности,
+годность настроек и полноту покрытия. Отвечает он теми же кусками, что и
+остальные команды: блок покрытия — это ровно ответ `size check`, а не второй
+расчёт. Код выхода — первый по важности, а не «что-то нашлось»: `2` настройки
+нечитаемы (читать больше нечего), `3` история обрезана, `1` покрытие неполно,
+`4` число приближённо, `0` делать нечего. Датчик, о котором настройки молчат,
+назван ненужным, а не отсутствующим, и не загружается: словарь весит мегабайты,
+а платить за строку ответа, которой у чисел не было, нечем.
+
+В шаблонный CI (`templates/ci.yml`) полнота намеренно **не** входит: колонки в
+шаблоне — пример, и на проекте, где колонки ещё не подобраны, такая проверка была
+бы красной не по делу. Когда колонки обрисуют проект, её добавляют одной строкой
+(`pnpm exec size check`).
+
+Готовая строка для CI: `pnpm run test:sizes` — больше ничего не нужно: проверка —
+это и есть команда `size`, своего набора тестов потребителю ставить не надо.
+Подсказка `--init` говорит то же самое: проверка — команда пакета, своих файлов в
+проект она не приносит.
+
+В поставке лежит и готовое описание этой проверки: `templates/ci.yml` из пакета
+(`node_modules/@vernikr/size-report/templates/ci.yml`) кладётся в
+`.github/workflows/size-report.yml` без правок — сборка таблицы, сверка с файлом
+на диске, два снимка чисел (обычный и в среде без настроек git) и их сравнение.
+Секретов оно не требует. Для `npm`/`yarn` в самом файле сказано, какие две строки
+заменить. Рядом — `templates/size-report.config.json`, черновик настроек в дополнение
+к `pnpm exec size --init`: колонки в нём примерные (`README.md`, `package.json`),
+они есть почти в любом проекте, поэтому первый отчёт собирается сразу.
+
+Свой CI у пакета — `.github/workflows/ci.yml`: он гоняет у себя тот же список
+команд, что описан ниже, и его можно взять за образец для шага потребителя.
+
+| Код | Что случилось | Что делать |
+|---|---|---|
+| 0 | всё сходится | ничего |
+| 1 | таблица разошлась с историей (или правка на диске не закоммичена); у `size check` — путь истории не отслеживается и не исключён | `pnpm run sizes` и закоммитить таблицу; для `check` — дописать путь колонкой или в `skip` |
+| 2 | что-то в вызове или в проекте — **командная строка** (незнакомый ключ, ключ без значения, повтор ключа, два режима сразу, лишнее слово, команда и режим, неизвестная команда, несовместимый ключ, нет ответа в JSON, два ответа сразу, нет коммита); **настройки и проект** (нет файла настроек, настройки не разобраны, настройки неверны, нет git, не git-репозиторий, конфиг уже есть); **история** (нет такого коммита, коммит назван неточно, коммит вне истории); **хук** (чужой хук, чужой core.hooksPath, нечем звать инструмент); **измерение** (файл не JavaScript, минификатор не разобрал) | текст отказа называет причину и готовую команду — и она выполнима: это сторожит `test/refusals.test.js` |
+| 3 | неполная история (clone с `--depth`) | полный клон: `git fetch --unshallow` |
+| 4 | нет датчика | `minify.engine: "esbuild"`, а минификатора нет: числа получены упрощением. Отчёт собран, причина и починка — в тексте |
+| 5 | внутренняя ошибка | это дефект инструмента: текст нужен нам, см. «Ловушки» ниже |
+
+### 6. Отчёт обновляется сам после коммита (по желанию)
+
+```bash
+pnpm exec size install-hook     # поставить post-commit и post-merge
+pnpm exec size uninstall-hook   # снять и вернуть проект к прежнему поведению
+```
+
+Хуки ставятся **только этой командой**: ни один обычный запуск их не создаёт и
+проект до неё не меняется (файлы живут в `.git`, `git status` их не видит). После
+каждого коммита и слияния отчёт пересобирается, а если он лежит в git — ложится
+отдельным коммитом с подписью `chore(report): отчёт пересобран после <sha>`.
+Коммитится только путь отчёта: чужой индекс и незакоммиченная работа не тронуты.
+Слияние обрабатывается тем же входом, что обычный коммит, но другим файлом —
+`post-merge`: git создаёт коммит слияния сам и `post-commit` при этом не зовёт.
+
+Зацикливания нет по устройству, а не по флагу: коммит отчёта собирается
+плумбингом (`commit-tree` — хуков не зовёт), и сам отчёт строки не получает.
+Выключается автоматика двумя способами — `"hooks": {"enabled": false}` в
+настройках (хук остаётся, но молчит) или `size uninstall-hook`; в окружениях, где
+обновлять отчёт не нужно (CI, чужая машина, зависимости не поставлены), хук молчит
+сам и ничего не пишет в вывод коммита. Что он делает и чем кончился последний
+запуск, видно в `pnpm exec size doctor`; отказ инструмента коммит не роняет —
+причина едет одной строкой и остаётся в записи о запуске.
+
+### 7. Ловушки, найденные этой же инструкцией
+
+Две из них найдены прогоном и уже закрыты — они оставлены здесь как объяснение
+поведения, а не как обходные пути:
+
+- **Модуль в расширении `.js`** (`import`/`export` в `.js` — обычное дело в
+  проектах с бандлером) измеряется как любой другой файл, с `type: module` в
+  манифесте или без него: гард разбирает результат и как скрипт, и как модуль.
+  Раньше он пробовал только скрипт и падал кодом 5 на самом `export`, обвиняя
+  стриппер; сегодня это невозможно, и правки в настройках не требуются
+  (`REFACTOR.md` R-4.6);
+- **Не JavaScript в графе** (разметка или типы прямо в `.js`) — это код 2 и
+  отказ, который называет причину и что править. Причина берётся с того способа,
+  которым файл считали: при `minify.engine: "esbuild"` отказ называет минификатор
+  и даёт два выхода (расширению — упрощение в `minify.ext` или способ `strip`), а
+  при упрощении — `minify.guard`. Стеком такой случай не выглядит ни там, ни там;
+- **Минификатора нет** (установка без необязательных зависимостей, платформа без
+  `esbuild`) — метрика честно отступает к упрощению: числа те же, что у `strip`,
+  способ говорит об этом словами, а прогон отдаёт **код 4** с готовой починкой.
+  Проверить это без переустановки можно окружением `SIZE_REPORT_NO_OPTIONAL=1` —
+  тем же приёмом это делает `test/minify.test.js`;
+- **Разбор модуля — рабочий поток, поднятый один раз на прогон** (`REFACTOR.md`
+  R-5.4): сам разбор стоит ~0,1 мс, а платится за него стартовой ценой потока
+  (≈ 54 мс) — и только если в измеряемых файлах вообще есть модули. Отступление
+  к `node --check` (≈ 86 мс на клетку) осталось на случай, когда файла потока нет
+  в упаковке, поток не ответил или в Node нет модулей vm;
+- **Новый файл-колонка должен быть закоммичен** до запуска: иначе проверка
+  состояния скажет «не совпало с деревом коммита» (сначала `git add` + коммит,
+  потом `pnpm run sizes`);
+- **Доковая правка — тоже правка.** Коммит, тронувший `WORKLOG.md` или любой
+  файл-колонку, получает в таблице строку, поэтому после него таблицу собирают
+  заново — иначе проверка говорит «расходится с историей git» и называет строку.
+  Незакоммиченная правка таблицу не двигает («сейчас» берётся из коммита), поэтому
+  сборка не ломается от того, что рядом с ней правят доки.
+- **`--init` не правит `.gitignore`** (`REFACTOR.md` R-4.8) — добавьте отчёты
+  руками, если им не место в истории.
+
+Проверено не на словах: раздел пройден покомандно на свежем репозитории (три
+коммита, ESM в `src/`) — протокол и найденные расхождения в `WORKLOG.md` §16, а
+пути, которые README называет своими, сверены с деревом. За этим следит сторож
+документации, и он падает вместе с документом, а не по желанию (`REFACTOR.md`
+R-4.1): пути, таблица файлов, зовы и ключи инструкций, числа проверок и цели по
+времени, ссылки на разделы и пин установки проверяются машинно. Формулировки,
+смысл и обещания о будущем машиной не проверяются — их держит человек.
+
+### 8. Если в проекте уже лежит копия инструмента
+
+Порядок выше — для проекта, который подключает инструмент впервые. Когда копия
+уже лежит (свои `size-table.js` и его тесты), шаги идут в другом порядке; ниже —
+тот, которым переезжал `safe-resets` (`WORKLOG.md` §18):
+
+1. **Установить, не удаляя копию** — две реализации какое-то время сосуществуют,
+   и это даёт бесплатную сверку на одном дереве: команда пакета с конфигом проекта
+   обязана собрать тот же артефакт байт в байт (у `safe-resets` — 225 673 Б,
+   sha256 `1bdb27e1…`). Не совпало — дальше не идём.
+2. **Перевести команды проекта на пакет:** `"test:sizes": "size"`,
+   `"sizes": "size --write"`.
+3. **Удалить копию** — и инструмент, и его тест: те же утверждения проверяет
+   набор пакета, а в проекте остаётся одна команда. Если тест звался из общего
+   раннера, шаг раннера становится одним и зовёт команду пакета, а не файл
+   проекта (в `safe-resets` путь берётся из манифеста установленного пакета,
+   чтобы шаг не знал внутренних имён файлов).
+4. **Убрать колонки удалённых файлов из настроек** и пересобрать артефакт
+   **отдельным коммитом**: коммиты, трогавшие только эти файлы, без них не
+   двигают ни одного числа, а такие коммиты строк не получают (у `safe-resets`
+   95 × 27 → 91 × 25).
+5. **Почистить документацию проекта:** ссылки на файлы инструмента заменяются
+   именем пакета и его командами, а описание внутренностей (стриппер, чтение
+   истории пачкой, вёрстка) из доков проекта уходит в доки пакета — иначе их две
+   копии и они разойдутся.
+
+Доступа к пакету не требуется ни локально, ни в CI — репозиторий публичный (§1),
+поэтому шага с ключом в этом порядке нет.
+
+Что при этом теряется: проверки, которые сверяли настройки проекта с ожиданиями
+инструмента, отдельным набором больше не идут. Большую часть закрывает сама
+команда (чужой ключ или незнакомая метрика в конфиге — отказ с объяснением, файл
+таблицы не может быть колонкой), но _содержимое_ подписи (заголовок и команда
+починки взяты из конфига) не проверяет никто: если это важно, это одна проверка
+поверх `--data` в проекте.
+
+## Для ИИ-агента
+
+- `size check --json` — готово ли всё: какая часть истории покрыта, какие пути
+  мимо колонок (с коммитом-первопричиной) и какие коммиты выпали без строки.
+- `size explain <коммит> --json` — почему у конкретного коммита нет строки: причина,
+  тронутые файлы (колонки, исключённые, непокрытые) и готовая починка. Коммит —
+  именем ревизии (`HEAD`, ветка, тег), полным sha или его началом.
+- `size measure --json` — данные без вёрстки: строки, числа, суммы. Сегодня это
+  `--json` (прежняя форма, заморожена эталоном) и `--data` (контракт страницы).
+- `--json` — форма ответа, а не отдельный режим, и правило у него одно: ответ
+  бывает ровно у четырёх вызовов. Без команды это прежняя форма данных
+  (заморожена эталоном паритета), у `check`, `explain` и `doctor` — их ответ.
+  У команды без ответа и рядом с режимом (`--write`, `--data`, `--page`, `--init`)
+  он отказ, а не тишина: просить JSON там, где его не бывает, — ошибка вызова.
+- `size doctor --json` — вся диагностика одним ответом: окружение, зависимости,
+  настройки, покрытие и находки с уровнем (`action` — делать, `note` — знать).
+- Коды выхода: `0` всё хорошо · `1` расхождение с историей или неполнота ·
+  `2` настройки, окружение, неизвестное или лишнее слово, два режима сразу ·
+  `3` неполная история · `4` нет датчика · `5` внутренняя ошибка (таблица —
+  `PLAN.md` §4.1). Действуют уже сейчас: отказ — это код и одна строка с готовой
+  командой починки, без стека. `--help` печатает и то, и другое.
+- Прогонов два, и оба названы: `pnpm test` — быстрый (каждая правка), `pnpm test:all` —
+  полный (выкладка и CI); что в каком и почему — `tools/suites.js`, печатает числа и
+  стоимости сам прогон.
+- Разбор аргументов один на входе и до чтения проекта: режим либо один, либо
+  отказ с обоими названными; команда и режим вместе не работают; ключ без
+  значения и ключ, названный дважды, — такой же отказ. Поэтому зов, который
+  инструмент не понял, нельзя спутать с исправным прогоном: вместо нуля придёт
+  код 2 и готовая команда.
+
+## Ловушки, на которых стоит проверять движок
+
+Фикстура (`fixtures/synthetic/history.bundle`) — это история, в которой
+собрано то, на чём ломаются такие инструменты: `//` внутри строки, регексп с
+экранированным слэшем, шаблон с выражением, `.mjs` с `export`, не-английское имя
+файла, CRLF, переименование файла, коммит «только отчёт», смешанный коммит,
+слияние с правкой разрешения конфликта, замена символа без изменения объёма,
+удаление и возврат файла, пустой файл, незнакомое расширение. Полный список — в
+`fixtures/synthetic/README.md`.
+
+```bash
+pnpm test                      # быстрый прогон (каждая правка): паритет на фикстуре,
+                               # контракт данных и страница, сторож документации и выпуска
+pnpm test:all                  # полный прогон (выкладка и CI): то же плюс интеграционные —
+                               # сборка на дисках, сверка с деревом, хуки, метрики
+pnpm run suites:measure        # перемерить стоимости файлов набора
+pnpm run parity:live           # паритет с живым проектом на клоне, две среды
+node bin/size.js --data        # контракт данных: страница и агент
+node bin/size.js --page        # минимальная страница отчёта
+node bin/size.js --help        # справка и коды выхода
+pnpm run parity                # переснять эталон паритета: проект и ревизия — из манифеста
+pnpm run fixture               # пересобрать фикстуру и её эталон
+pnpm run pack:check            # работает ли движок из собранного тарболла
+pnpm run check:standards       # эталоны воспроизводятся, а дерево остаётся чистым
+git clone fixtures/synthetic/history.bundle /tmp/size-report-fixture
+```
+
+Открытые блокеры и известные пробелы — в `BLOCKERS.md`; там же таблица настроек,
+которые проверены и оказались инертными (чтобы не проверять их заново).