report annotations

Модель результатов проверки текста CheckResults

Эта модель содержит в себе информацию достаточную для того, чтобы отобразить пользователю состояние ошибок в его тексте в полном объёме, как в редакторе Литеры.

/**
 * Типы ошибок на закладке "Правописание"
 */
enum OrthoKind {
   /**
    * Орфография
    */
   SPELLING = 'mkSpelling',
   
   /**
    * Грамматика
    */
   GRAMMAR = 'mkGrammar',
   
   /**
    * Пунктуация
    */
   PUNCTUATION = 'mkPunctuation',
 
   /**
    * Стилистика
    */
   STYLE = 'mkStyle',
 
   /**
    * Семантика
    */
   SEMANTIC = 'mkSemantic',
 
   /**
    * Типографика
    */
   TYPOGRAPHY = 'mkTypography',
 
   /**
    * Буква Ё
    */
   YO = 'mkYo',
 
   /**
    * Оформление
    */
   PAPER_STRUCTURE = 'mkPaperStructure',
}

/**
 * Типы ошибок на закладке "Красота"
 */
enum CiceroKind {
   /**
    * Тавтологии
    */
   TAUTOLOGY = 'mkTautology',
 
   /**
    * Неблагозвучие
    */
   PHONICS = 'mkPhonics',
   
   /**
    * Орфоэпия
    */
   ORTHOEPY = 'mkOrthoepy',
 
   /**
    * Синонимы
    */
   SYNONYM = 'mkSynonym',
 
   /**
    * Эпитеты
    */
   EPITHET = 'mkEpithet',
 
   /**
    * Родная речь
    */
   NATIVE_SPEECH = 'mkNativeSpeech',
}

/**
 * Типы ошибок на закладке "Качество"
 */
enum QualityKind {
   /**
    * Водность
    */
   WATER = 'mkWater',
}

/**
 * Координаты в файле ogxt
 */
interface Position {
  /**
   * начало выделения
   */
  start: number;
  
  /**
   * конец выделения
   */
  end: number;
}

/**
 * Модель одной аннотации
 */
interface Annotation {
  /**
   * Идентификатор аннотации
   */
  id: number;

  /**
   * Тип ошибки
   */
  kind: OrthoKind | CiceroKind | QualityKind;

  /**
   * Кусочек текста, который содержит ошибку (plain text)
   */
  selection: string;

  /**
   * Координаты позиций в файле ogxt где находится selection (может быть 
   * несколько, например, для повторяющихся частей текста)
   */
  position: Position[];

  /**
   * Краткое описание ошибки (html), содержит в основном простой текст, 
   * но могут встречаться акцентирования текста при помощи тэгов `<i>`, 
   * `<b>` и тому подобное. Сложного поведение не предполагается.
   */
  description: string;

  /**
   * Подсказка (html) 
   * Произвольный текст с описанием того, что пользователь может сделать с ошибкой, 
   * включая лингвистические комментарии (например: "удалите запятую, если...").
   * Здесь могут быть линки `<a>` с дополнительными атрибутами `data-kind` и 
   * `data-word`. 
   * - `data-kind` — это тип действия, которое может совершить пользователь, 
   *   оно может принимать следующее значение:
   *   - `replace-whole` - выделенную часть текста (`selection`) можно 
   *     заменить на текст из атрибута `data-word`.
   * - `data-word` — какое значение нужно в это действие подставить.
   * 
   * Могут быть и просто ссылки на внешние ресурсы, например, словари или поисковики.
   * 
   * Также часть подсказки может быть выделена при помощи тэгов <u> — это 
   * более подробное место ошибки, например, ошибочная буква или знак 
   * препинания.
   *
   * Если предложенных вариантов действий очень много (например для проверок 
   * орфоэпии или синонимов), то они могут быть сгруппированы в пачки при 
   * помощи тэгов `<group>`. Некоторое количество предложенных вариантов может
   * быть дополнительно собрано внутрь тэга `<more>`. Интерфейс Литеры 
   * отображает группы вариантов в виде элементов списка, а если внутри группы 
   * ещё имеется и тэг `<more>`, то этот список становится 
   * открывающимся/закрывающимся, показывая только часть вариантов в закрытом 
   * состоянии или все (включая те, что внутри `<more>`).
   * 
   * Если же тэгом `<more>` выделены некоторые варианты за пределами тэга 
   * `<group>`, то интерфейс Литеры добавляет в текст подсказки кнопку​ 
   * "Ещё...", которая показывает варианты спрятанные внутри этого `<more>`.
   *
   * У тэга `<more>` могут быть дополнительыне атрибуты:
   * - `data-btn` - это подпись для кнопки "Ещё..."
   * - `data-title` - это текст для всплывающей подсказки для кнопки "Ещё..."
   */
  suggestion?: string;

  /**
   * Идентификатор аннотации из которой нужно взять подсказку.
   * 
   * Не может быть заполнено одновременно с полем suggestion. 
   * Бывает или suggestion, или suggestionId, но не вместе.
   */
  suggestionId?: string;

  /**
   * Подробное объясление ошибки (html) с возможными ссылками на библиотеку 
   * правил или иные первоисточники ещё более подробно разъясняющие суть ошибки
   * и возможности к её исправлению. 
   * Может содержать линк `<a>` с дополнительным атрибутом `data-kind` и `data-word`: 
   * - `data-kind` — это тип действия, может принимать одно значение:
   *   - `add-word` - слово из атрибута `data-word` можно добавить в частный словарь
   * - `data-word` — какое значение нужно в это действие подставить.
   */
  explanation: string;

  /**
   * Внутренний номер нарушенного правила
   */
  rule: string;

  /**
   * Идентификатор группы, когда несколько аннотаций логически сгруппированы 
   * в одну суть.
   * Например, однокоренные слова для синонимов
   */
  group?: string;
}

/**
 * Результаты проверки
 */
interface CheckResults {
  /**
   * Подписи к типам ошибок (только те, которые встречаются в отчёте)
   */
  kinds: {
    [key: string]: string;
  };

  /**
   * массив обнаруженных проблем
   */
  annotations: Annotation[];

  /**
   * Результаты базовой проверки текста на водность
   */
  water: {
    /**
     * Доля водных слов в тексте (число от 0 до 1)
     */
    content: number;
  };

  /**
   * Результаты базовой проверки текста на частотные сочетания
   */
  collocations: {
    /**
     * Доля частотных повторений из двух слов в тексте (число от 0 до 1)
     */
    bigram: number;

    /**
     * Доля частотных повторений из трёх слов в тексте (число от 0 до 1)
     */
    trigram: number;

    /**
     * Доля частотных повторений из четырёх и более слов в тексте (число от 0 до 1)
     */
    ngram: number;
  };
}

Примечание: поля вида group?: string; (с вопросиком в конце имени) - это необязательные поля, которых может не быть в модели.

Отчёт о результатах проверки может быть получен только при использовании метода POST check-ogxt-results. Общая схема работы с API с целью самостоятельной обработки результатов проверки описана на страничке Проверка текста.