Подсветка Ansible в VS Code: модуль, параметры и ключи задачи разными цветами

Коротко. Смысловую подсветку Ansible даёт языковой сервер расширения Red Hat, тема только выбирает цвета. Проверьте, что язык файла Ansible, и задайте четыре правила с суффиксом :ansible. Опечатка в параметре станет видна до запуска плейбука.

В YAML всё устроено одинаково: ключ, двоеточие, значение. Поэтому модуль ansible.builtin.template, его параметр dest и ключ задачи when в редакторе часто одного цвета, и опечатка dset: вместо dest: всплывает только при запуске плейбука. Ниже о том, откуда в VS Code берётся подсветка по смыслу, как её включить в любой теме и что сделать с Jinja, Helm и Jenkinsfile.

Симптом

Роль открыта в VS Code, и всё в задаче окрашено примерно одинаково. Модуль не отличается от ключа name, параметры модуля не отличаются от переменных. Глаз ищет структуру по отступам.

Ошибки в именах параметров находит только Ansible:

fatal: [web1]: FAILED! => {"msg": "Unsupported parameters for (ansible.builtin.template) module: dset."}

Почему так

Подсветку в VS Code делают два слоя.

Первый слой это грамматика: набор регулярных выражений, который знает только синтаксис. Для YAML это ключи, строки, числа и комментарии. Модуль и параметр с точки зрения грамматики одно и то же: ключ.

Второй слой это смысловая подсветка от языкового сервера. Расширение Ansible от Red Hat знает модули и их документацию и размечает задачу по смыслу:

Что в задаче	Как размечает сервер	Пример
Модуль	`class`	`ansible.builtin.template`
Параметр из документации модуля	`method`	`src`, `dest`, `mode`
Ключ задачи	`keyword`	`name`, `when`, `loop`, `register`
Остальные ключи	`property`	переменные в `vars`

Дальше цвет выбирает тема. Она красит class и method так, как привыкла красить классы и методы в обычных языках. В одной теме модуль получится бирюзовым, а параметр жёлтым, в другой оба окажутся почти одного цвета. Задачи Ansible тема при этом в виду не имела.

Смысловая разметка появляется только тогда, когда у файла язык Ansible. Расширение узнаёт роли по путям вроде roles/*/tasks/main.yml и playbooks/*.yml. При другой раскладке файл остаётся обычным YAML, и второго слоя нет совсем.

Диагностика

Внизу справа в строке состояния должно быть написано Ansible. Если там YAML, сервер этот файл не разбирает.
Поставьте курсор на имя модуля и выполните команду Developer: Inspect Editor Tokens and Scopes. В блоке semantic token должен быть тип class, а язык ansible.
Если типа нет, откройте Output и выберите в списке Ansible Server. Там видно, нашёл ли сервер Python и Ansible.

Что смотрим	Где	Норма
Язык файла	строка состояния	Ansible
Тип токена у модуля	Inspect Editor Tokens and Scopes	`class`, язык `ansible`
Сервер запущен	Output → Ansible Server	нет ошибок про Python и ansible

Что сделать

Поставьте расширение Ansible от Red Hat. Если сервер не видит Ansible, укажите интерпретатор Python, в котором он установлен, в настройке ansible.python.interpreterPath.
Привяжите файлы ролей к языку Ansible, если расширение не узнало их само. Пример ниже.
Включите смысловую подсветку явно: "editor.semanticHighlighting.enabled": true. По умолчанию её включает или выключает тема.
Задайте цвета четырём ролям. Правила работают в любой теме.

"files.associations": {
  "**/roles/**/*.yml": "ansible",
  "**/playbooks/*.yml": "ansible"
},
"editor.semanticTokenColorCustomizations": {
  "rules": {
    "class:ansible":    { "foreground": "#FF7ED0", "bold": true },
    "method:ansible":   "#52F0FF",
    "keyword:ansible":  { "foreground": "#B897FF", "bold": true },
    "property:ansible": "#7AB4FF"
  }
}

Суффикс :ansible ограничивает правило файлами Ansible. Без него те же цвета получат классы и методы в Python, Go и всех остальных языках со смысловой подсветкой.

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

Jinja, Helm и Jenkinsfile

Jinja. Переменные и фильтры внутри {{ }} размечает грамматика того же расширения. Удобно, когда переменная в {{ }} отличается цветом от той же переменной в defaults: объявление и использование не путаются.

Helm. Шаблоны в templates/ получают язык helm от расширения Kubernetes. Всё выражение {{ … }} в его грамматике лежит в одной области, поэтому тема, которая делает её жирной, превращает шаблон в сплошную жирную стену. Ещё одна особенность: расширение объявляет {{ и }} парными скобками, и встроенная раскраска пар скобок красит их по глубине вложенности, поверх цвета темы.

Jenkinsfile. Встроенная грамматика Groovy не знает декларативный пайплайн. stages, steps и post для неё обычные слова, поэтому файл почти белый. Это лечится маленькой дополнительной грамматикой, которую VS Code подмешивает к Groovy:

{
  "scopeName": "jenkins.dsl.injection",
  "injectionSelector": "L:source.groovy -string -comment",
  "patterns": [
    { "name": "keyword.control.jenkins.groovy",
      "match": "\\b(pipeline|agent|environment|stages|stage|steps|post|when|script|parallel)\\b(?=\\s*[({])" },
    { "name": "support.function.jenkins.groovy",
      "match": "\\b(sh|checkout|withCredentials|withEnv|timeout|retry|junit|archiveArtifacts)\\b(?=\\s*[(\\s'\"{])" }
  ]
}

Грамматика подключается из любого расширения через contributes.grammars с injectTo: ["source.groovy"]. Строки и комментарии она не трогает, это задаёт -string -comment в селекторе.

Всё перечисленное мы собрали в бесплатную тему Violet Ops: в ней эти правила, грамматика для Jenkinsfile и цвета для Jinja и Helm уже настроены, исходник открыт.

Чего не делать

Задавать правила class, method и keyword без суффикса :ansible. Через минуту классы в Python станут розовыми и жирными, а причину придётся искать.
Красить ключи задачи и обычный текст в один оттенок. Тогда name: и значение без кавычек сливаются, даже если ключ жирный.
Полагаться только на цвет. Каждый двенадцатый мужчина плохо различает часть оттенков. Жирный шрифт у модулей и ключей задачи оставляет структуру видимой и для них.