Диагностические сообщения в Parcel представляют собой унифицированный формат описания ошибок, предупреждений и информационных сообщений, возникающих на этапах сборки, трансформации модулей и работы плагинов. Архитектура диагностики построена вокруг идеи машинно-читаемых структур, которые одновременно подходят для CLI-вывода, интеграции с IDE и автоматизированной обработки в плагинах.
Ключевая особенность системы заключается в разделении:
Такой подход позволяет отделить логику формирования ошибки от её представления пользователю.
Каждое диагностическое сообщение в Parcel представляет собой объект с фиксированным набором полей. Несмотря на расширяемость, существует ядро структуры, которое присутствует практически всегда.
type Diagnostic = {
message: string,
code?: string,
severity: 'error' | 'warning' | 'info',
origin?: string,
filePath?: string,
language?: string,
stack?: string,
hints?: Array<string | DiagnosticHint>,
documentationURL?: string,
name?: string,
diagnosticCode?: number
};Человеко-читаемое описание проблемы. Это основное содержимое, которое выводится в консоль или интерфейс IDE.
Определяет критичность:
error — блокирует сборкуwarning — не блокирует, но требует вниманияinfo — информационное сообщениеСтроковый идентификатор категории ошибки. Используется для группировки и быстрого поиска причин.
Примеры:
BABEL_TRANSFORM_ERRORRESOLVE_FAILEDFS_MODULE_NOT_FOUNDСистема кодов в Parcel служит нескольким целям:
Код обычно представляет собой строку в формате:
<DOMAIN>_<COMPONENT>_<TYPE>RESOLVE — ошибки резолва модулейTRANSFORM — ошибки трансформации кодаFS — файловая системаCACHE — кэшированиеOPTIMIZER — оптимизация бандлаRESOLVE_MODULE_NOT_FOUNDTRANSFORM_SYNTAX_ERRORFS_INVALID_PATHCACHE_WRITE_FAILEDОдним из ключевых компонентов диагностики является точное указание места возникновения проблемы.
type DiagnosticLocation = {
filePath: string,
start: {
line: number,
column: number
},
end?: {
line: number,
column: number
}
};Parcel может расширять location следующими данными:
Code frame — это текстовое представление участка кода с подсветкой ошибки.
Пример логики формирования:
10 | const a = 10;
11 | const b = a();
^
12 | console.log(b);Поле hints содержит дополнительные рекомендации для
исправления ошибки.
type DiagnosticHint = {
message: string,
language?: 'text' | 'markdown',
code?: string
};Hints могут быть как простыми строками, так и структурированными объектами с дополнительной логикой отображения.
Parcel использует строгую модель приоритетов:
error — прерывает сборкуwarning — отображается, но не блокируетinfo — логическая информация о процессеПоле origin определяет компонент, породивший
сообщение.
parcel@parcel/resolver-default@parcel/transformer-babel@parcel/optimizer-terserПомимо строковых кодов, Parcel поддерживает числовые идентификаторы:
diagnosticCode?: numberПоле stack содержит стек вызовов, приведший к
ошибке.
Error: Unexpected token
at transform (babel-transformer)
at parse (parser)
at loadModule (resolver)Parcel агрегирует сообщения по нескольким признакам:
При выводе в терминал диагностическая система преобразует объект в человекочитаемый формат:
? RESOLVE_MODULE_NOT_FOUND
Cannot find module 'react'
/src/index.js:1:17
> 1 | import React from 'react';
^^^^^^^^^^^^
Hint: Install package 'react' using npm or yarn.Sourcemaps играют ключевую роль в точности диагностических сообщений.
Плагины Parcel могут генерировать собственные диагностические сообщения.
origincodefilePath и
locationhintsПеред передачей между процессами диагностика сериализуется:
Диагностические коды используются для:
Архитектура Parcel допускает расширение структуры Diagnostic без нарушения обратной совместимости.