Cookstyle

[edit on GitHub]

Cookstyle — это инструмент проверки кода, который помогает вам писать лучшие кулинарные книги Chef Infra, обнаруживая и автоматически исправляя стилистические, синтаксические и логические ошибки в вашем коде.

Cookstyle работает на основе движка проверки RuboCop. RuboCop поставляется с более чем тремя сотнями правил, или «копами», предназначенными для обнаружения распространённых ошибок в написании кода на Ruby и обеспечения соблюдения единого стиля кодирования. Мы настроили Cookstyle с подмножеством этих копов, которые, по нашему мнению, идеально подходят для разработки кулинарных книг. Мы также предоставляем специфичные для Chef копы, которые ловят распространённые ошибки в коде кулинарных книг, очищают ненужные части кода и обнаруживают устаревшие элементы, препятствующие работе кулинарных книг в последних версиях Chef Infra Client.

Cookstyle повышает качество кода, благодаря:

• Обеспечению соблюдения стилистических соглашений и лучших практик.
• Помощи каждому члену команды в написании кода с одинаковой структурой.
• Поддержанию единообразия в исходном коде.
• Установлению ожиданий для коллег (и будущих) участников проекта.
• Обнаружению устаревшего кода, который создаёт ошибки после обновления до более новой версии Chef Infra Client.
• Обнаружению распространённых ошибок Chef Infra, которые приводят к сбоям или неправильному поведению кода.

Cookstyle по сравнению с Rubocop

Cookstyle более стабилен, чем Rubocop, и настроен для кода кулинарных книг Chef. Это означает, что проверка кулинарных книг с помощью Cookstyle будет более последовательной и менее вероятна привести к ошибкам в тестах CI.

Настроенные копы

Разработка кулинарных книг отличается от традиционной разработки Ruby-приложений, поэтому мы поддерживаем настроенный набор встроенных копов из Rubocop. Копы, которые бесполезны для разработки кулинарных книг, отключены, и иногда мы изменяем конфигурацию правила, чтобы обеспечить иное поведение. Мы также расширили базовый пакет RuboCop набором собственных копов, специфичных для Chef Infra. Эти копы встречаются только в Cookstyle и помогут вам создавать более надёжные и перспективные кулинарные книги.

Новые копы

Новые копы постоянно добавляются в Rubocop. Новые копы могут привести к сбоям в тестах CI для существующих кодовых баз и заставить авторов постоянно обновлять свой код.

С Cookstyle мы обновляем движок RuboCop для исправления ошибок и повышения производительности, но мы меняем только набор копов, которые приведут к ошибкам в тестах, один раз в год во время основных релизов Chef Infra в апреле. Все новые копы вводятся на уровне предупреждений «рефакторинг» в RuboCop, что означает, что они будут отображаться на экране при запуске Cookstyle, но не будут вызывать сбои в сборке. Эта стабильность позволяет вам свободно обновлять версии Cookstyle, не вынуждая обновлять ваш инфраструктурный код.

Запуск Cookstyle

Cookstyle запускается из командной строки, обычно для одной кулинарной книги и всех файлов Ruby в ней:

cookstyle /path/to/cookbook

Cookstyle также может быть запущен из корня каталога отдельной кулинарной книги:

cookstyle .

Cookstyle возвращает список, через стандартный вывод, показывающий результаты оценки:

Inspecting 8 files
CWCWCCCC

Offences:

cookbooks/apache/attributes/default.rb:1:1: C: Missing utf-8 encoding comment.
default["apache"]["indexfile"] = "index1.html"
^
cookbooks/apache/attributes/default.rb:1:9: C: Prefer single-quoted strings when you don't
need string interpolation or special symbols.
default["apache"]["indexfile"] = "index1.html"
        ^^^^^^^^
cookbooks/apache/attributes/default.rb:1:19: C: Prefer single-quoted strings when you
don't need string interpolation or special symbols.
default["apache"]["indexfile"] = "index1.html"
                  ^^^^^^^^^^^

Вывод

Вывод Cookstyle:

• Указывает количество найденных и проанализированных файлов. Например: Inspecting 8 files
• Перечисляет результаты этих файлов как серию символов. Например: CWCWCCCC
• Для каждого символа указывает имя файла, номер строки, номер символа, тип проблемы или ошибки, описывает проблему или ошибку и указывает местоположение в исходном коде, где находится проблема или ошибка

Оценка Cookstyle имеет следующий синтаксис:

FILENAME:LINE_NUMBER:CHARACTER_NUMBER: TYPE_OF_ERROR: MESSAGE
SOURCE CODE
^^^^^^^^^^^

Например:

cookbooks/apache/attributes/default.rb:1:9: C: Prefer single-quoted strings when you don't
need string interpolation or special symbols.
default["apache"]["indexfile"] = "index1.html"
        ^^^^^^^^

Символы

В стандартном выводе отображаются следующие символы, используемые для обозначения результата оценки:

Автокоррекция предупреждений Cookstyle

Многие копы Cookstyle включают возможность автоматической коррекции нарушений. Для автоматической коррекции кода выполните следующую команду из каталога кулинарной книги:

cookstyle -a .

После выполнения этой команды обязательно проверьте, что логика автоматической коррекции привела к соответствующему коду кулинарной книги.

.rubocop.yml

Используйте файл .rubocop.yml в кулинарной книге для переопределения значений по умолчанию в Cookstyle для включённых и отключённых правил. При оценке будут использоваться только включенные правила, которые либо определены в файле enabled.yml самого Cookstyle, либо правила, явно включенные в файле .rubocop.yml кулинарной книги. Любое правило, которое больше не нужно, следует отключить в файле .rubocop.yml.

Каждая кулинарная книга имеет свой собственный файл .rubocop.yml, что означает, что у каждой кулинарной книги может быть свой собственный набор включённых, отключённых и настраиваемых правил. Тем не менее, для всех кулинарных книг чаще всего используется один и тот же набор включённых, отключённых и настраиваемых правил. Когда RuboCop выполняется для кулинарной книги, сначала загружается полный набор включённых и отключённых правил (как определено в файлах enabled.yml и disabled.yml самого Cookstyle), а затем они сравниваются с настройками в файле .rubocop.yml кулинарной книги.

Настраиваемые правила должны быть указаны в файле .rubocop.yml. Состояние правил — включено или выключено — в файле .rubocop.yml имеет приоритет над состоянием правил, определённым в файлах enabled.yml и disabled.yml.

Синтаксис

Файл .rubocop.yml имеет следующий синтаксис:

NAME_OF_RULE:Description:'a description of a rule'Enabled :(true or false)KEY:VALUE

где

• NAME_OF_RULE — имя правила
• Description — строка, которая печатается в стандартном выводе и описывает правило, если оно активируется во время оценки
• Enabled включает (true) или отключает (false) правило; для правил, не являющихся настраиваемыми, это значение переопределяет настройки в файлах enabled.yml и disabled.yml в Cookstyle
• KEY: VALUE добавляет дополнительные детали для правила, если это необходимо. Например, Max: 200 устанавливает длину строки в 200 символов для правила LineLength

.rubocop_todo.yml

Используйте файл .rubocop_todo.yml для записи текущего состояния всех оценок, а затем запишите их в файл. Это позволяет просматривать оценки по одной. Отключите бесполезные оценки, а затем обработайте остальные.

Для создания файла .rubocop_todo.yml выполните следующую команду:

cookstyle --auto-gen-config