Типы ошибок в unified

В экосистеме unified, к которой относятся библиотеки Remark и Rehype, ошибки обрабатываются строго и систематически. Ошибки могут возникать на разных этапах обработки данных: при разборе исходного текста, трансформациях AST (Abstract Syntax Tree), генерации выходного контента или при работе с плагинами. Важно понимать классификацию этих ошибок, их свойства и способы безопасной обработки.

1. Ошибки парсинга (ParseError)

Описание: Парсер отвечает за преобразование исходного текста (Markdown, HTML) в AST. Ошибки парсинга возникают при нарушении синтаксиса исходного документа.

Признаки:

  • Недопустимые символы в исходном тексте.
  • Неправильное вложение элементов.
  • Некорректные идентификаторы ссылок или изображений.

Свойства объекта ошибки:

  • message — описание ошибки.
  • line, column — позиция в исходном документе, где возникла ошибка.
  • reason — краткое объяснение причины.
  • source — имя парсера, который вызвал ошибку.

Пример обработки:

import { unified } from 'unified';
import remarkParse from 'remark-parse';

try {
  const tree = unified()
    .use(remarkParse)
    .parse('Некорректный [синтаксис');
} catch (error) {
  console.error(`Ошибка парсинга на строке ${error.line}, колонка ${error.column}: ${error.reason}`);
}

2. Ошибки трансформации AST (TransformerError)

Описание: После того как исходный документ разобран, он превращается в AST. Трансформеры (плагины) могут изменять структуру дерева. Ошибки трансформации возникают, если плагин получает неожиданный формат узла или не может корректно применить изменения.

Типичные ситуации:

  • Узел AST имеет недопустимые свойства или тип.
  • Плагин ожидает обязательное поле, которого нет в узле.
  • Нарушение ограничений схемы AST.

Свойства объекта ошибки:

  • node — узел AST, на котором произошла ошибка.
  • plugin — имя плагина, вызвавшего ошибку.
  • reason — описание причины ошибки.

Пример обработки:

import remark from 'remark';
import remarkHtml from 'remark-html';

const processor = remark().use(remarkHtml);

processor.process('Текст с нестандартным узлом')
  .catch(error => {
    console.error(`Ошибка плагина ${error.plugin}: ${error.reason}`);
  });

3. Ошибки генерации (CompilerError)

Описание: На этапе генерации выходного формата (HTML, Markdown, другие форматы) могут возникнуть ошибки, если AST содержит недопустимые узлы или структура дерева не поддерживается генератором.

Примеры причин:

  • Неподдерживаемый тип узла.
  • Противоречивые атрибуты элементов.
  • Ошибки при сериализации текста.

Свойства объекта ошибки:

  • node — узел, вызвавший ошибку генерации.
  • reason — описание проблемы.
  • filePath — путь исходного файла, если он известен.

4. Ошибки плагинов (PluginError)

Описание: Плагины являются самостоятельными модулями с собственными проверками и ограничениями. Они могут выбрасывать ошибки, если:

  • Нарушены требования к конфигурации.
  • Переданы некорректные опции.
  • Плагин столкнулся с непредвиденными данными.

Свойства объекта ошибки:

  • plugin — имя плагина.
  • options — переданные опции.
  • reason — описание ошибки.
  • node — опционально, узел AST, на котором произошла ошибка.

Рекомендации по работе с PluginError:

  • Всегда проверять входные опции.
  • Оборачивать вызовы плагина в try/catch.
  • Логировать узлы AST для упрощения отладки.

5. Ошибки валидации AST (VFileMessage и VFileError)

Описание: Библиотека vfile, используемая в unified, добавляет стандартизированную систему сообщений об ошибках и предупреждений. Она позволяет:

  • Присваивать ошибки конкретным файлам.
  • Указывать точное положение в исходном тексте.
  • Создавать предупреждения и информационные сообщения, не прерывая процесс.

Основные поля VFileMessage:

  • message — текст ошибки.
  • reason — причина.
  • position — объект с start и end (line, column, offset).
  • source — имя плагина или парсера.

Особенности:

  • VFileMessage может быть предупреждением (fatal: false) или критической ошибкой (fatal: true).
  • Позволяет накапливать сообщения об ошибках без остановки процесса.

6. Отличие критических ошибок от предупреждений

  • Критические ошибки (fatal) — прерывают обработку, требуют немедленного исправления.
  • Предупреждения (non-fatal) — информируют о потенциальных проблемах, не мешают генерации результата.

Использование строгой типизации ошибок и систематическая обработка позволяет:

  • Улучшить диагностику проблем в Markdown/HTML документах.
  • Повысить стабильность пайплайна unified.
  • Облегчить интеграцию сторонних плагинов без неожиданных сбоев.

7. Практика безопасной обработки

  • Оборачивать каждый этап пайплайна в try/catch.
  • Логировать ошибки с указанием типа, источника и позиции.
  • Использовать VFile для хранения всех сообщений.
  • В тестах проверять не только корректные входные данные, но и сценарии с ошибками.
Оглавление