Режим verbose
Режим verbose в SWC используется для получения расширенного диагностического вывода во время компиляции и трансформации JavaScript/TypeScript кода. Его основная задача — раскрыть внутренние этапы обработки исходного кода: парсинг, преобразования AST, применение пресетов, работу плагинов и итоговую генерацию кода. Такой режим особенно важен при отладке сложных сборок, где поведение трансформаций зависит от множества факторов.
### Уровни вывода и назначение verbose
В стандартном режиме SWC ограничивается минимальным набором сообщений: ошибки компиляции и критические предупреждения. Verbose-режим расширяет этот поток, добавляя детализированные события выполнения:
* этапы обработки каждого файла;
* информация о применённых трансформациях;
* сведения о времени выполнения отдельных стадий;
* данные о загрузке конфигурации;
* сообщения о подключённых плагинах и пресетах.
Расширенный вывод позволяет наблюдать не только результат, но и процесс формирования результата.
### CLI-флаг verbose
В CLI SWC verbose-режим активируется через флаг:
```bash
swc src -d dist --verbose
```
или в сокращённой форме:
```bash
swc src -d dist -v
```
При включении данного режима процесс компиляции начинает сопровождаться подробными логами, отображающими последовательность действий для каждого обрабатываемого файла.
Типичный поток сообщений включает:
* обнаружение входного файла;
* чтение конфигурации;
* парсинг исходного кода в AST;
* применение трансформаций;
* генерацию итогового JavaScript;
* запись результата на диск.
### Логика формирования диагностического вывода
Verbose-режим строится вокруг событийной модели выполнения. Каждое действие компилятора может быть отражено в логах как отдельное событие. Внутренне это соответствует этапам pipeline:
1. **Resolution phase**
* определение путей файлов;
* применение ignore-правил;
* обработка расширений.
2. **Parsing phase**
* преобразование исходного текста в AST;
* фиксация синтаксических ошибок.
3. **Transformation phase**
* применение модулей трансформации;
* работа с JSX, TypeScript, ESNext-конструкциями.
4. **Generation phase**
* сериализация AST в код;
* оптимизация вывода.
Verbose-режим маркирует каждую из стадий временными метками, позволяя оценивать стоимость отдельных шагов.
### Отображение времени выполнения
Одним из ключевых элементов verbose-режима является профилирование. В логах фиксируются:
* общее время обработки файла;
* время парсинга;
* время трансформаций;
* время генерации кода.
Пример структуры вывода:
```
[swc] processing: index.ts
[swc] parse: 12ms
[swc] transform: 34ms
[swc] generate: 8ms
[swc] total: 54ms
```
Такая детализация используется для выявления узких мест в сборке, особенно в монорепозиториях или проектах с большим количеством трансформаций.
### Конфигурационные аспекты
Хотя verbose-режим в первую очередь управляется CLI, его поведение может зависеть от общей конфигурации SWC. В частности, влияние оказывают:
* включённые пресеты (`jsc.transform`, `env`, `react`);
* наличие TypeScript-режима;
* использование minify-прохода;
* подключённые плагины.
Каждый из этих элементов добавляет дополнительные этапы в pipeline, которые становятся видимыми в verbose-логах.
### Взаимодействие с плагинами
При использовании пользовательских или сторонних плагинов verbose-режим фиксирует:
* момент загрузки плагина;
* применение к конкретному AST-узлу;
* результат трансформации;
* возможные ошибки внутри плагина.
Это позволяет локализовать проблемы, возникающие не на уровне компилятора, а внутри расширений.
### Поведение при ошибках
В случае синтаксических или трансформационных ошибок verbose-режим расширяет стандартное сообщение:
* указывает стадию, на которой произошёл сбой;
* выводит контекст обработки;
* фиксирует файл и позицию в исходном коде;
* при необходимости отображает частично построенный AST.
Такой формат упрощает диагностику сложных ошибок, особенно в случаях некорректных трансформаций JSX или TypeScript.
### Интеграция с системами сборки
При использовании SWC через сборщики (Webpack, Vite, Rollup через плагины) verbose-режим передаётся через параметры соответствующих интеграционных модулей.
Пример концептуальной передачи параметров:
```javascript
{
jsc: {
parser: {
syntax: "typescript"
}
},
verbose: true
}
```
В таких сценариях логирование может агрегироваться сборщиком, что приводит к смешанному выводу: часть сообщений поступает от SWC, часть — от обёртки.
### Анализ производительности
Verbose-режим часто используется как инструмент профилирования. На основе логов можно выделить:
* файлы с аномально долгим парсингом;
* трансформации, создающие избыточную нагрузку;
* влияние JSX-конверсии на общий билд;
* стоимость генерации больших AST.
Это позволяет принимать решения о:
* упрощении трансформационных цепочек;
* отключении ненужных пресетов;
* разделении бандла на части.
### Типовые сценарии диагностики
В логах verbose-режима часто выявляются следующие категории проблем:
**Замедление на этапе трансформации**
* чрезмерное использование Babel-подобных преобразований;
* сложные макросы или кастомные плагины.
**Неожиданное увеличение времени парсинга**
* большие файлы с глубокой вложенностью AST;
* использование экспериментального синтаксиса.
**Дублирование обработки файлов**
* неправильная конфигурация watcher-режима;
* конфликт расширений входных файлов.
### Отличие verbose от стандартного режима
Обычный режим SWC ориентирован на минимизацию вывода и максимальную скорость. Verbose-режим вводит дополнительную нагрузку:
* увеличение I/O операций;
* рост объёма логов;
* возможное снижение скорости сборки.
При этом функционально он не изменяет результат компиляции, влияя исключительно на наблюдаемость процесса.
### Форматирование логов
Логи verbose-режима, как правило, структурируются следующим образом:
* префикс источника (`[swc]`);
* имя файла;
* стадия обработки;
* временные метки;
* итоговые статусы.
Такая структура обеспечивает возможность последующей автоматической обработки логов внешними инструментами анализа.
### Поведение в watch-режиме
В режиме наблюдения verbose-вывод становится потоковым. Для каждого изменения файла фиксируются:
* повторный запуск pipeline;
* дифф обработки между версиями файла;
* повторное применение трансформаций.
Это позволяет отслеживать деградацию производительности в динамике.
### Ограничения использования verbose
При увеличении количества файлов verbose-режим генерирует значительный объём данных. Это приводит к:
* росту нагрузки на консольный вывод;
* усложнению анализа логов без фильтрации;
* снижению общей скорости выполнения за счёт логирования.
В крупных проектах часто используется выборочное включение verbose только для отдельных модулей или стадий сборки.