docs: сделать проверку типов frontend release gate и убрать известное ограничение

bundle_ui запускает `pnpm run typecheck` перед сборкой bundle. И наличие шага,
и его порядок закреплены приёмкой — вместе с требованием vue-tsc версии 3 и
выше и с запретом снова совмещать сборку и проверку в build:prod.

Из docs/02 убран раздел «Известное ограничение: проверка типов frontend почти
ничего не проверяет» и заменён описанием действующего контракта. Прогноз в нём
был близок, но неточен: ошибок оказалось 142, а не ~155, и класс DefaultRow/
PeerVo на Element Plus 2.3 не существовал вовсе — он появился вместе с
обновлением Element Plus.

docs/04 получил описание модели отображения (третий слой рядом с типизированной
моделью и сырым YAML) и раздел о том, что страница Hysteria теперь read-only на
всех уровнях, а не только визуально.

docs/11: команды проверки frontend и dev doctor в раздел запуска, семь новых
пунктов приёмки.
This commit is contained in:
2026-08-30 07:44:51 +05:00
parent 32ff47731c
commit 219bb364bc
6 changed files with 209 additions and 18 deletions
+28 -18
View File
@@ -111,28 +111,38 @@ Bun обновляется отдельно от остальных: оркес
полного прохода `bun test → tsc → compile → приёмка на Debian`, а не строки в
общем патче.
### Известное ограничение: проверка типов frontend почти ничего не проверяет
### Проверка типов frontend — обязательный шаг релиза
`pnpm run build:prod` выполняет `vite build && vue-tsc --noEmit`, но `vue-tsc`
здесь версии `0.35.0` (2022 год) и шаблоны Vue практически не типизирует.
Проверка проходит зелёной, не давая гарантии, которую обещает.
```text
pnpm run typecheck → vue-tsc --noEmit → ОБЯЗАН пройти
pnpm run build:prod → vite build
pnpm run verify → typecheck, затем build
```
Замер сделан: на паре `typescript@5.9` + `vue-tsc@2.2` тот же исходный код даёт
**около 155 ошибок типов** в четырёх файлах — почти все одного вида
(`possibly 'undefined'` при обращении к необязательным полям модели конфига
Hysteria в шаблоне) плюс несовместимость `DefaultRow` с `PeerVo` в слотах
таблицы пиров.
`bundle_ui()` запускает `typecheck` **до** сборки bundle: собирать production
bundle из кода, который не проходит проверку типов, незачем. Порядок и сам факт
наличия шага проверяются приёмкой.
Это не дефект безопасности и не блокер релиза: ошибки существуют в коде уже
сейчас и ни на что в рантайме не влияют. Но обновление typechecker'а тянет за
собой обновление `vue` (3.2 → 3.5, иначе `vue-tsc` 2.x не разбирает
`JSX.IntrinsicElements`), а за ним — `element-plus`, `pinia` и `vue-router`.
То есть это отдельная работа с собственной проверкой на живой панели, а не
строка в security-патче.
До v1 этой гарантии не было. `build:prod` означал `vite build && vue-tsc
--noEmit`, но `vue-tsc` был версии `0.35.0` (2022 год) и шаблоны Vue
практически не типизировал: проверка проходила зелёной, не давая гарантии,
которую обещает. Хуже того — на Vue 3.5 она ломается сама, потому что не знает
`vue/jsx-runtime`, то есть пережить обновление Vue всё равно не могла.
Ограничение на безопасность не влияет: уязвимые пакеты frontend обновляются
независимо от версии typechecker'а, движением lockfile внутри уже объявленных
диапазонов (см. `pnpm.overrides` в `apps/frontend/package.json`).
Современный `vue-tsc 3.3` на том же коде дал **142 ошибки**: 141 × `TS18048`
(«possibly undefined» при обращении к необязательным секциям конфига Hysteria в
шаблоне) и одна `TS2322`, всё в двух файлах представления Hysteria. Ожидавшегося
класса «`DefaultRow` несовместим с `PeerVo`» на Element Plus 2.3 не было вовсе —
он появился позже, вместе с обновлением Element Plus до 2.14, где слоты таблицы
типизированы строже.
Закрыто это не подавлением, а границей: `api/config/hysteriaViewModel.ts`
превращает ответ сервера в модель, где присутствие каждой секции — свойство
типа. Подробности — в [docs/04](04-admin-panel.md).
Контракт теперь читается так:
> проверка типов SFC-шаблонов проходит, и это доказывает сборка, а не намерение.
### Проверка зависимостей на уязвимости