129 lines
14 KiB
Markdown
129 lines
14 KiB
Markdown
# P20 · октябрь 2019 · миграция JavaScript на TypeScript — тройное ревью
|
||
|
||
Статус: **принят в публикационный слой 31 июля 2026 года**. Registry применяет
|
||
три revision по стабильным slug и сохраняет дату и автора базового архива:
|
||
|
||
- <code>editorial-2019-10-practice-typescript-migration</code>;
|
||
- <code>editorial-2019-10-mechanism-typescript-migration</code>;
|
||
- <code>editorial-2019-10-field-typescript-migration</code>.
|
||
|
||
Модуль экспортирует ровно три revision без полей <code>date</code> и
|
||
<code>author</code>. При прямом вызове с <code>--print-revisions</code> он
|
||
печатает только JSON, совпадающий с import-safe export. В статьях типы,
|
||
fixture и метрики показаны как методы проверки; ни один вымышленный
|
||
production-результат не выдан за измерение.
|
||
|
||
## Проход 1. Факты и техника — пройдено
|
||
|
||
| Утверждение или решение | Первичный источник | Проверенная граница |
|
||
| --- | --- | --- |
|
||
| JavaScript-синтаксис допустим в TypeScript, поэтому файл можно переносить постепенно, а не одномоментно | [TypeScript Handbook: Migrating from JavaScript](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) | Практика не обещает массовое переименование; в маршруте сохранены соседние JavaScript-модули |
|
||
| TypeScript-специфичные конструкции не становятся runtime-проверкой после компиляции | [TypeScript Handbook: Migrating from JavaScript](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html), [TypeScript 3.5 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/) | В механизме type alias отделён от исполняемого normalizer; сетевой payload не объявлен проверенным только из-за interface |
|
||
| <code>allowJs</code> принимает JavaScript-файлы рядом с TypeScript, что подходит для поэтапного переноса | [TSConfig: allowJs](https://www.typescriptlang.org/tsconfig/allowJs.html) | Конфигурация fixture держит <code>allowJs</code> и <code>noEmit</code>; она не меняет format модулей и output production-сборки |
|
||
| <code>checkJs</code> выдаёт diagnostics для JavaScript; локальный <code>@ts-check</code> позволяет начать с одного файла | [TSConfig: checkJs](https://www.typescriptlang.org/tsconfig/checkJs.html) | В practice и field <code>@ts-check</code> стоит в одном boundary-файле, а не выдаётся за включение проверки всего legacy-дерева |
|
||
| TypeScript 3.5 уже содержит нужную для примера эпоху: проверку JavaScript, <code>unknown</code>, type predicates и релизные изменения вокруг generic checking | [TypeScript 3.5 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/) | Нет позднего синтаксиса, <code>satisfies</code>, optional chaining, Zod, современных стратегий Node module resolution или заявлений зрелости 2027 года |
|
||
|
||
### Честная граница фикстур
|
||
|
||
Код normalizer проверяет учебный объект <code>Member</code> и предназначен для
|
||
трёх контролируемых входов: валидный объект, объект без <code>email</code> и
|
||
объект с чужим <code>status</code>. Он показывает, где runtime-код должен
|
||
остановить неясный payload. Фикстура не вызывает реальный API, не измеряет
|
||
скорость сборки и не подтверждает ответ конкретной сетевой библиотеки.
|
||
|
||
Конфигурация с <code>noEmit</code> — безопасный первый режим проверки, а не
|
||
совет заменить существующий delivery pipeline. Если конкретный проект
|
||
генерирует JavaScript через <code>tsc</code>, интегратор обязан отдельно
|
||
сопоставить <code>target</code>, <code>module</code>, output path и реальную
|
||
production-команду. Этот риск в статьях назван ограничением, а не скрыт
|
||
обещанием «переход пройдёт безболезненно».
|
||
|
||
Вердикт прохода: **пройден**. Технические утверждения привязаны к официальным
|
||
источникам TypeScript, а свойства, зависящие от конкретного проекта, оставлены
|
||
явными задачами проверки.
|
||
|
||
## Проход 2. Редактура и голос М2 / 2019 — пройдено
|
||
|
||
| Ревизия | Симптом и цена в начале | Главный вопрос | Практический артефакт и ограничение |
|
||
| --- | --- | --- | --- |
|
||
| Практика | Массовый rename создаёт any и останавливает выпуск; цена — длинная ветка без полезной проверки данных | Как начать миграцию с границы и сохранить build | tsconfig fixture, JSDoc normalizer, таблица границ и выпускной маршрут; процент .ts не выдан за качество |
|
||
| Механизм | Файл уже .ts, но неверный payload доходит до экрана; цена — место ответственности скрыто за any | Почему типы исчезают в runtime и где ставить проверку | сравнение исходника и JavaScript, normalizer <code>unknown → Member</code>, таблица ролей; статический анализ не выдан за runtime-защиту |
|
||
| Полевой разбор | Legacy transport отдаёт <code>response.body</code> напрямую; цена — неясный откат и риск сломать delivery | Как перенести один поток без массового rewrite | автономная fixture transport → normalizer → screen и четыре gate; нет заявления о запуске реального сервера |
|
||
|
||
- Первые два абзаца каждой статьи называют симптом, проблему и стоимость
|
||
неверного маршрута. Дальше текст держит цепочку: симптом → причина →
|
||
проверка → действие → ограничение.
|
||
- Речь короткая и техническая: вместо общих оценок названы
|
||
<code>allowJs</code>, <code>checkJs</code>, <code>noEmit</code>,
|
||
<code>unknown</code>, <code>any</code>, normalizer, contract fixture,
|
||
type-check и build gate.
|
||
- Автор соответствует М2 / 2019: он уже связывает frontend-код, delivery и
|
||
API-границу, но не приписывает себе поздние практики платформенной команды,
|
||
SLO, современную схему валидации или зрелую организационную программу
|
||
миграции.
|
||
- Три текста не дублируют друг друга: практика задаёт маршрут, механизм
|
||
разбирает исчезновение типов и роль <code>any</code>, полевой разбор
|
||
собирает минимальную выпускную партию.
|
||
- Объём, число разделов, таблица с <code>caption</code>/<code>thead</code>,
|
||
код, упорядоченный маршрут, figure с alt/caption и два или больше источника
|
||
подлежат независимой автоматической проверке draft gate.
|
||
|
||
Вердикт прохода: **пройден**. Тексты сохраняют практический голос автора
|
||
2019 года и не подменяют решение эффектными обещаниями.
|
||
|
||
## Проход 3. Визуал и выпуск — пройдено в пределах автономного пакета
|
||
|
||
- <code>typescript-migration-lane-2019.svg</code> показывает четыре малых
|
||
шага: baseline выпуска, границу данных, локальный <code>@ts-check</code> и
|
||
один TypeScript-модуль; выпускные gate вынесены в нижний блок. Визуал не
|
||
предлагает переписать всё дерево файлов.
|
||
- <code>typescript-migration-type-boundary-2019.svg</code> противопоставляет
|
||
нормальный путь <code>unknown → runtime normalizer → Member</code> красному
|
||
обходу через <code>any</code>. Это уточняет границу ответственности, а не
|
||
дублирует таблицу из статьи.
|
||
- <code>typescript-migration-release-gates-2019.svg</code> отделяет contract
|
||
fixture, type-check, существующий build и smoke. Четыре карточки прямо
|
||
показывают, что один успешный gate не доказывает остальные.
|
||
- У всех SVG есть <code>title</code>, <code>desc</code>,
|
||
<code>role="img"</code> и <code>aria-labelledby</code>. В статьях
|
||
предусмотрены самостоятельные содержательные alt-тексты и
|
||
<code>figcaption</code>. SVG не содержат JavaScript, внешних URL,
|
||
<code>foreignObject</code> или растровых data URI.
|
||
- Независимый мобильный preflight отрисовал каждый SVG через Sharp в PNG
|
||
шириной 375 px. Первый вариант двух схем содержал слишком мелкие вторичные
|
||
подписи. Их заменили на вертикальные композиции с короткими подписями;
|
||
повторный рендер не показал обрезания, наложения или горизонтального
|
||
выхода. Это проверка статичных схем, а не browser-review страницы.
|
||
- После подключения registry строгий аудит подтвердил три revision, а
|
||
production build сгенерировал 374 статические страницы. Реальный browser
|
||
review остаётся отдельной проверкой поведения и не заявлен как выполненный.
|
||
|
||
### Фактические проверки
|
||
|
||
Запускаются следующие независимые проверки:
|
||
|
||
<pre><code>node --check web/scripts/upgrade-2019-10.mjs
|
||
cd web && npm run audit:draft -- scripts/upgrade-2019-10.mjs
|
||
xmllint --noout \
|
||
web/public/assets/editorial/2019/typescript-migration-lane-2019.svg \
|
||
web/public/assets/editorial/2019/typescript-migration-type-boundary-2019.svg \
|
||
web/public/assets/editorial/2019/typescript-migration-release-gates-2019.svg</code></pre>
|
||
|
||
Результат независимого запуска 31 июля 2026 года:
|
||
|
||
| Проверка | Результат |
|
||
| --- | --- |
|
||
| <code>node --check</code> | PASS, синтаксис модуля корректен |
|
||
| <code>--print-revisions</code> и import-safe export | PASS внутри draft gate: stdout — только JSON, export совпадает с CLI и содержит ровно три revision |
|
||
| <code>npm run audit:draft -- scripts/upgrade-2019-10.mjs</code> | PASS: 9 756 / 9 495 / 10 347 знаков основного текста; у каждого текста есть проблема в начале, пять или больше разделов, figure, таблица, код, маршрут и источники |
|
||
| <code>xmllint --noout</code> для трёх SVG | PASS, XML корректен |
|
||
| Strict audit после подключения registry | PASS: 9 756 / 9 495 / 10 347 знаков; по одному figure и table, по два code example |
|
||
| <code>npm run build</code> | PASS, code 0, 374 статические страницы |
|
||
| Scope/self-review | PASS: в revision нет date/author; в SVG нет script, foreignObject, внешних ссылок или data URI; <code>articles.json</code> не перезаписан |
|
||
|
||
Выпусковой вердикт: **тройное ревью пройдено, пакет принят к публикации**.
|
||
<code>articles.json</code> не менялся; registry заменяет только редакционные
|
||
поля по стабильному slug. Поведение на реальной странице в выбранном браузере
|
||
нужно проверить отдельно: production build и raster preflight этого не
|
||
подменяют.
|