Інтерфейс аналізатора

Уся взаємодія із сайтом Exercism відбувається автоматично. В аналізаторів єдина відповідальність: приймати рішення й повертати статус та будь-які повідомлення.

Виконання

  • Аналізатор має надавати виконуваний скрипт. Докладніше про це йдеться у файлі docker.md.
  • Скрипт отримує три параметри:
    • Слаг вправи (наприклад, two-fer).
    • Шлях до каталогу з надісланими файлами (із завершальним слешем).
    • Шлях до каталогу вихідних даних (із завершальним слешем). Цей каталог доступний для запису.
  • Скрипт мусить записати файл analysis.json у каталог вихідних даних.
  • Скрипт має записати файл tags.json у каталог вихідних даних.

Дозволений час виконання

Аналізатор отримує 100% ресурсів машини на 20 секунд для кожного рішення. Після 20 секунд процес зупиняють, і він повідомляє про тайм-аут.

Note

Радимо дотримуватися нашого документа з найкращими практиками продуктивності, щоб зменшити ймовірність тайм-аутів.

Формат вихідних даних

analysis.json

Файл analysis.json має бути структурований так:

{
  "summary": "This solution looks good but has a few points to address",
  "comments": [
    {
      "comment": "ruby.general.some_parameterised_message",
      "params": { "foo": "param1", "bar": "param2" },
      "type": "essential"
    },
    {
      "comment": "ruby.general.some_unparameterised_message",
      "params": {},
      "type": "actionable"
    },
    {
      "comment": "ruby.general.some_unparameterised_message"
    },
    "ruby.general.some_unparameterised_message"
  ]
}

summary (необовʼязкове)

Поле summary містить текст (не Markdown), який підсумовує результат. У ньому може бути щось на кшталт «Ваше рішення майже готове, залишилося лише дві невеликі зміни.» або «Код працює чудово, але є дрібні зауваження від лінтера, які варто виправити.». Цей підсумок показується на сайті над коментарями.

comments

Поле comments містить масив коментарів, які посилаються на документи Markdown у репозиторії exercism/website-copy (докладніше див. у розділі Як писати коментарі аналізатора). Кожне значення в масиві може бути або рядком-вказівником, або обʼєктом JSON такого формату:

comment

Рядок-вказівник на файл у website-copy.

params (необовʼязкове)

Обʼєкт JSON, що містить параметри, які слід підставити під час рендерингу. Наприклад, у файлі Markdown можна написати Try %{variable_name} += 1 instead, а потім задати params як { "variable_name": "foo"}, щоб підставити замість %{variable_name} ту змінну, яку насправді використав студент.

Якщо використовуються файли з параметрами, усі входження % треба екранувати, додаючи перед ними ще один %. Наприклад: Try aim aim for 100%% of the tests passing.

type (необовʼязкове)

Допустимі такі значення type:

  • essential: ми мʼяко блокуємо студентів, доки вони не опрацюють цей коментар
  • actionable: будь-який коментар, що дає користувачеві конкретну вказівку, як покращити рішення
  • informative: коментарі, що дають інформацію, але не обовʼязково передбачають, що студенти нею скористаються. Наприклад, у Ruby, якщо хтось використовує конкатенацію рядків у вправі TwoFer, ми також розповідаємо про форматування рядків, але не радимо його як кращий варіант.
  • celebratory: коментарі, які кажуть користувачам, що вони зробили щось правильно, або як загальний відгук про рішення, або щодо певного прийому.

Коментарі без поля type типово мають тип informative .

Зараз на сайті ми мʼяко блокуємо студентів на коментарях essential, радимо їм опрацювати коментарі actionable, перш ніж позначати рішення як завершене в практичних вправах (але не в концептуальних), і не пропонуємо жодних дій щодо коментарів informative чи celebratory. Утім, згодом ми можемо додати емодзі чи позначки до інших типів або згрупувати їх окремо.

tags.json

Файл tags.json має бути структурований так:

{
  "tags": [
    "construct:list",
    "paradigm:functional",
    "technique:higher-order-functions",
    "uses:List.unfold"
  ]
}

tags

Поле tags містить масив рядків тексту (англ. string). Кожен тег має формат: "<category>:<thing>".

Ось кілька прикладів:

  • "paradigm:functional"
  • "technique:recursion"
  • "construct:bitwise-and"
  • "uses:DateTime.add_seconds"

Теги можна використовувати, щоб визначити, які конструкції, прийоми чи парадигми використовує рішення.

Докладніше див. у розділі Як позначати рішення тегами.

Налагодження

Вміст stdout і stderr з кожного запуску зберігається у файлах, які можна переглянути пізніше.

Можна створити файл analysis.out, що містить налагоджувальну інформацію, яку потім можна буде переглянути.

Що почитати далі

Перш ніж будувати аналізатор, радимо прочитати наш посібник з аналізаторів.