Cookstyle

[изменить на 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