protolint-mcp

by yoheimuta

Integrations

  • Supports running protolint in GitHub workflows through various actions including github/super-linter, plexsystems/protolint-action, and yoheimuta/action-protolint

  • Supports JetBrains GoLand through the intellij-protolint plugin for Protocol Buffer linting

  • Integrates with JetBrains IDEs through the intellij-protolint plugin for Protocol Buffer linting

протолинт

protolint — это подключаемая утилита для линтинга/исправления файлов Protocol Buffer (proto2+proto3):

  • Работает быстро, так как не требует компилятора.
  • Легко следовать официальному руководству по стилю. Правила и руководство по стилю точно соответствуют друг другу.
    • Fixer автоматически исправляет все возможные нарушения официального руководства по стилю.
  • Позволяет отключать правила с комментарием в файле буфера протокола.
    • Это полезно для проектов, в которых необходимо поддерживать совместимость с API и при этом максимально строго соблюдать руководство по стилю.
    • Некоторые правила можно автоматически отключить, добавив комментарии к обнаруженным нарушениям.
  • Загружает плагины для хранения ваших пользовательских правил линтинга.
  • Прошел проверку по всем правилам.
  • Множество интеграционных поддержек.
    • плагин протокола
    • Интеграция редактора
    • Действие GitHub
    • Интеграция CI

Демо

После настройки сервера MCP вы можете попросить любые клиенты MCP, такие как Claude Desktop, выполнить линтинг и исправить ваши файлы буфера протокола следующим образом:

Кроме того, vim-protolint работает следующим образом.

MCP-сервер

protolint теперь поддерживает протокол контекста модели (MCP) , который позволяет моделям ИИ напрямую взаимодействовать с protolint.

Использование

protolint --mcp

Подробную документацию по использованию и интеграции функциональности сервера MCP Protolint см. в документации MCP .

Установка

Через Homebrew

protolint можно установить для Mac или Linux с помощью Homebrew через кран yoheimuta/protolint .

brew tap yoheimuta/protolint brew install protolint

Поскольку homebrew-core включает protolint, вы также можете установить его просто brew install protolint. Это tap по умолчанию, который устанавливается по умолчанию. Он проще, но не поддерживается тем же автором. Чтобы поддерживать его в актуальном состоянии, я рекомендую вам сначала запустить brew tap yoheimuta/protolint .

Через GitHub Releases

Вы также можете загрузить готовый двоичный файл с этой страницы релиза:

В разделе загрузок каждого релиза вы можете найти готовые двоичные файлы в пакетах .tar.gz.

Используйте поддерживаемый образ Docker

protolint поставляет образ Docker yoheimuta/protolint , который позволяет использовать protolint как часть рабочего процесса Docker.

❯❯❯ docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint _example/proto [_example/proto/invalidFileName.proto:1:1] File name should be lower_snake_case.proto. [_example/proto/issue_88/oneof_options.proto:11:5] Found an incorrect indentation style " ". " " is correct. [_example/proto/issue_88/oneof_options.proto:12:5] Found an incorrect indentation style " ". " " is correct.

Из источника

Бинарник можно установить из исходного кода, если доступен Go. Однако я рекомендую использовать один из готовых бинарных файлов, поскольку он не содержит информации о версии.

go install github.com/yoheimuta/protolint/cmd/protolint@latest

В JavaScript/TypeScript

Вы можете использовать protolint с помощью менеджера пакетов nodejs, например npm или yarn .

$ npm install protolint --save-dev

Это добавит ссылку на зависимость разработки в ваш локальный package.json .

Во время установки будет вызван скрипт install.mjs . Он загрузит соответствующий protolint с github. Так же, как @electron/get , вы можете обойти загрузку, используя следующие переменные среды:

Переменная средыЗначение по умолчаниюОписание
PROTOLINT_MIRROR_HOSThttps://github.comБазовый URL-адрес HTTP/веб-сервера, на котором размещены двоичные файлы
PROTOLINT_MIRROR_REMOTE_PATHyoheimuta/protolint/загрузка/релизыПуть к архивам на удаленном хосте
PROTOLINT_MIRROR_USERNAMEИмя пользователя базовой аутентификации HTTP
PROTOLINT_MIRROR_PASSWORDПароль базовой аутентификации HTTP
ПРОТОЛИНТ_ПРОКСИHTTP(S)-прокси с дополнительными данными аутентификации

В удаленном пути архивы со страницы релизов должны быть зеркальными.

После этого вы можете использовать npx protolint (со всеми предоставленными аргументами protolint) в своих dev-скриптах.

{ ... "scripts": { "protoc": "....", "preprotoc": "npx protolint" }, ... }

Вы можете добавить узел protolint в свой package.json , который может содержать содержимое protolint.yml под узлом lint , т. е. корневым элементом конфигурации будет protolint .

Если вы хотите получить вывод, соответствующий компилятору TSC, используйте reporter tsc .

В проектах Python

Вы можете использовать protolint как линтер в своих проектах python, wheel protolint-bin на pypi содержит предварительно скомпилированные двоичные файлы для различных платформ. Просто добавьте нужную версию в свой pyproject.toml или requirements.txt .

Загруженные wheels будут содержать скомпилированные двоичные файлы go для protolint и protoc-gen-protolint . Ваша платформа должна быть совместима с поддерживаемыми бинарными платформами.

Конфигурацию linter можно добавить в пакет tools.protolint в pyproject.toml .

Использование

protolint lint example.proto example2.proto # file mode, specify multiple specific files protolint lint . # directory mode, search for all .proto files recursively protolint . # same as "protolint lint ." protolint lint -config_path=path/to/your_protolint.yaml . # use path/to/your_protolint.yaml protolint lint -config_dir_path=path/to . # search path/to for .protolint.yaml protolint lint -fix . # automatically fix some of the problems reported by some rules protolint lint -fix -auto_disable=next . # this is preferable when you want to fix problems while maintaining the compatibility. Automatically fix some problems and insert disable comments to the other problems. The available values are next and this. protolint lint -auto_disable=next . # automatically insert disable comments to the other problems. protolint lint -v . # with verbose output to investigate the parsing error protolint lint -no-error-on-unmatched-pattern . # exits with success code even if no file is found (file & directory mode) protolint lint -reporter junit . # output results in JUnit XML format protolint lint -output_file=path/to/out.txt # output results to path/to/out.txt protolint lint -plugin ./my_custom_rule1 -plugin ./my_custom_rule2 . # run custom lint rules. protolint list # list all current lint rules being used protolint version # print protolint version protolint --version # print protolint version (global flag) protolint -v # print protolint version (when used as the only argument)

protolint не требует настройки по умолчанию, для большинства проектов он должен работать «из коробки».

Интеграция контроля версий

protolint доступен как pre-commit hook. Добавьте это в ваш .pre-commit-config.yaml в вашем репозитории, чтобы запустить protolint с Go:

repos: - repo: https://github.com/yoheimuta/protolint rev: <version> # Select a release here like v0.44.0 hooks: - id: protolint

или альтернативно используйте это для запуска protolint с Docker:

repos: - repo: https://github.com/yoheimuta/protolint rev: <version> # Select a release here like v0.44.0 hooks: - id: protolint-docker

Интеграция редактора

Код Visual Studio

JetBrains IntelliJ IDEA, GoLand, WebStorm, PHPStorm, PyCharm...

Vim ( движок ALE )

Vim ( синтаксис )

Действие GitHub

Действие GitHub для запуска protolint в ваших рабочих процессах

Интеграция CI

Плагины Jenkins

Конкретный вывод для окружающей среды

Можно отформатировать линтинг в соответствии с форматированием среды CI/CD. Среда должна быть установлена с использованием формата вывода. В настоящее время реализован следующий вывод:

СредаЗначение командной строкиОписаниеПример
Действия Githubci-ghПомощь с Github::warning file=example.proto,line=10,col=20,title=ENUM_NAMES_UPPER_CAMEL_CASE::EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES
AzureDevOps-решенияci-azПомощь Azure DevOps##vso[task.logissue type=warning;sourcepath=example.proto;linenumber=10;columnnumber=20;code=ENUM_NAMES_UPPER_CAMEL_CASE;]EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES
Gitlab CI/CDci-глабОбратное проектирование на основе примеровWARNING: ENUM_NAMES_UPPER_CAMEL_CASE example.proto(10,20) : EnumField name \"SECOND.VALUE\" must be CAPITALS_WITH_UNDERSCORES

Вы также можете использовать универсальный форматтер ci , который создаст универсальный сопоставитель проблем.

С помощью значения ci-env вы можете указать шаблон из следующих переменных среды:

Переменная средыПриоритетЗначение
PROTOLINT_CIREPORTER_TEMPLATE_STRING1Строка, содержащая Go-шаблон
PROTOLINT_CIREPORTER_TEMPLATE_FILE2Путь к файлу, содержащему Go-шаблон

Полученный перевод строки добавлять не нужно, так как он будет добавлен автоматически.

Доступны следующие поля:

Severity : серьёзность в виде строки (примечание, предупреждение или ошибка)

File : Путь к файлу, содержащему ошибку.

Line : Строка в file , содержащая ошибку (начальная позиция)

Column : Столбец в file , содержащий ошибку (начальная позиция)

Rule : Название правила, которое является ошибочным.

Message : Сообщение об ошибке, описывающее ошибку.

Создание выходного файла и потока ошибок CI/CD

Вы можете создать определенный вывод, соответствующий вашей среде CI/CD, а также создать выходной файл, например, для ваших инструментов статического анализа кода, таких как github CodeQL или SonarQube.

Это можно сделать, добавив флаг --add-reporter . Обратите внимание, что значение должно быть отформатировано как <reporter-name>:<output-file-path> (без < и > ).

$ protolint --reporter ci-gh --add-reporter sarif:/path/to/my/output.sarif.json proto/*.proto

Использовать как плагин протокола

protolint также поддерживает бинарный protoc-gen-protolint , который выполняет функциональность lint как плагин protoc. Подробности см. в cmd/protoc-gen-protolint/README.md .

Это полезно в ситуациях, когда у вас уже есть рабочий процесс плагина protoc.

Звонок из Go кода

Вы также можете использовать protolint из кода Go. Подробности смотрите в документации Go и lib/lint_test.go .

args := []string{"-config_path", "path/to/your_protolint.yaml", "."} var stdout bytes.Buffer var stderr bytes.Buffer err := lib.Lint(test.inputArgs, &stdout, &stderr)

Правила

Подробности смотрите в internal/addon/rules .

Набор правил следующий:

  • Официальное руководство по стилю . Это включено по умолчанию. По сути, эти правила могут исправить нарушения, добавив опцию -fix .
  • Неофициальное руководство по стилю. По умолчанию отключено. Вы можете включить каждое правило с помощью .protolint.yaml .

Опция -fix в командной строке может автоматически исправить все проблемы, о которых сообщают правила fixable. См. столбцы Fixable ниже.

Параметр -auto_disable в командной строке может автоматически отключить все проблемы, о которых сообщают правила автоматического отключения. Эта функция полезна, когда исправление существующих нарушений нарушает совместимость. См. столбцы AutoDisable ниже.

  • *1: Эти правила не должны поддерживать AutoDisable, поскольку исправления не нарушают их совместимость. Вам следует запустить protolint с -fix .
ОфициальноИсправимоАвтоотключениеИДЕНТИФИКАТОРЦель
ДаENUM_FIELD_NAMES_PREFIXПроверяет, что имена полей перечисления имеют префикс ENUM_NAME_UPPER_SNAKE_CASE.
ДаENUM_FIELD_NAMES_UPPER_SNAKE_CASEПроверяет, что все имена полей перечисления являются ЗАГЛАВНЫМИ_БУКВАМИ_С_ПОДЧЕРКАМИ.
ДаENUM_FIELD_NAMES_ZERO_VALUE_END_WITHПроверяет, что перечисление с нулевым значением должно иметь суффикс (например, "UNSPECIFIED", "INVALID"). Значение по умолчанию — "UNSPECIFIED". Вы можете настроить конкретный суффикс с помощью .protolint.yaml .
ДаENUM_NAMES_UPPER_CAMEL_CASEПроверяет, что все имена перечислений имеют CamelCase (с заглавной буквы).
Да*1FILE_NAMES_LOWER_SNAKE_CASEПроверяет, что все имена файлов имеют вид lower_snake_case.proto. Вы можете настроить исключенные файлы с помощью .protolint.yaml .
ДаFIELD_NAMES_LOWER_SNAKE_CASEПроверяет, что все имена полей разделены символом подчеркивания.
Да*1ИМПОРТ_СОРТИРОВКАПроверяет, что все импорты отсортированы.
ДаMESSAGE_NAMES_UPPER_CAMEL_CASEПроверяет, что все имена сообщений написаны в стиле CamelCase (с заглавной буквы).
Да*1ЗАКАЗПроверяет, что все файлы должны быть упорядочены определенным образом.
Да*1PACKAGE_NAME_LOWER_CASEПроверяет, что имя пакета должно содержать только строчные буквы.
ДаRPC_NAMES_UPPER_CAMEL_CASEПроверяет, что все имена rpc имеют формат CamelCase (с заглавной буквы).
ДаSERVICE_NAMES_UPPER_CAMEL_CASEПроверяет, что все названия служб написаны в стиле CamelCase (с заглавной буквы).
ДаПОВТОРЯЕМЫЕ_НАЗВАНИЯ_ПОЛЕЙ_МНОЖЕСТВЕННОПроверяет, что повторяющиеся имена полей являются именами во множественном числе.
Да*1ЦИТАТА_КОНСИСТЕНТНАЯПроверяет, что использование кавычек для строк является согласованным. По умолчанию используются двойные кавычки. Вы можете настроить конкретную кавычку с помощью .protolint.yaml .
Да*1ОТСТУПОбеспечивает последовательный стиль отступов. Стиль по умолчанию — 2 пробела. Вставка соответствующих новых строк также принудительно выполняется по умолчанию. Вы можете настроить детали с помощью .protolint.yaml .
Да*1PROTO3_FIELDS_AVOID_REQUIREDПроверяет, что все поля не являются обязательными для proto3.
Да_PROTO3_GROUPS_AVOIDПроверяет, что для proto3 следует избегать всех групп.
Да_*1МАКСИМАЛЬНАЯ_ДЛИНА_ЛИНИИУстанавливает максимальную длину строки. Длина строки определяется как количество символов Unicode в строке. Значение по умолчанию — 80 символов. Вы можете настроить детали с помощью .protolint.yaml .
Нет_-SERVICE_NAMES_END_WITHОбеспечивает согласованный суффикс для имен служб. Вы можете настроить конкретный суффикс с помощью .protolint.yaml .
Нет_-FIELD_NAMES_EXCLUDE_PREPOSITIONSПроверяет, что все имена полей не содержат предлоги (например, "for", "during", "at"). Вы можете настроить определенные предлоги и исключенные ключевые слова с помощью .protolint.yaml .
Нет_-MESSAGE_NAMES_EXCLUDE_PREPOSITIONSПроверяет, что все имена сообщений не содержат предлоги (например, «С», «Для»). Вы можете настроить определенные предлоги и исключенные ключевые слова с помощью .protolint.yaml .
Нет_-RPC_NAMES_CASEПроверяет, что все имена rpc соответствуют указанному соглашению. Вам необходимо настроить конкретное соглашение с помощью .protolint.yaml .
Нет_-СООБЩЕНИЯ_ИМЕЮТ_КОММЕНТАРИЙПроверяет, что все сообщения имеют комментарий. Вы можете настроить принудительное использование комментариев в стиле Golang с помощью .protolint.yaml .
Нет_-SERVICES_HAVE_COMMENTПроверяет, что все службы имеют комментарий. Вы можете настроить принудительное применение комментариев в стиле Golang с помощью .protolint.yaml .
Нет_-RPCS_HAVE_COMMENTПроверяет, что все rps имеют комментарий. Вы можете настроить принудительное применение комментариев в стиле Golang с помощью .protolint.yaml .
Нет_-FIELDS_HAVE_COMMENTПроверяет, что все поля имеют комментарий. Вы можете настроить принудительное использование комментариев в стиле Golang с помощью .protolint.yaml .
Нет_-ENUMS_HAVE_COMMENTПроверяет, что все перечисления имеют комментарий. Вы можете настроить принудительное использование комментариев в стиле Golang с помощью .protolint.yaml .
Нет_-ENUM_FIELDS_HAVE_COMMENTПроверяет, что все поля enum имеют комментарий. Вы можете настроить принудительное использование комментариев в стиле Golang с помощью .protolint.yaml .
Нет_-ФАЙЛ_ИМЕЕТ_КОММЕНТАРИЙПроверяет, начинается ли файл с комментария документа.
Нет_-СИНТАКСИС_ПОСЛЕДОВАТЕЛЬНЫЙПроверяет, что синтаксис — это указанная версия. По умолчанию — proto3. Вы можете настроить версию с помощью .protolint.yaml .

Я рекомендую вам добавить all_default: true в .protolint.yaml , поскольку все указанные выше линтеры включаются автоматически, так что вы всегда можете пользоваться максимальными преимуществами при каждом обновлении protolint.

Вот несколько примеров, которые показывают, что хороший стиль включен по умолчанию. - — плохой стиль, + — хороший стиль:

ENUM_FIELD_NAMES_PREFIX

enum FooBar { - UNSPECIFIED = 0; + FOO_BAR_UNSPECIFIED = 0; }

ENUM_FIELD_NAMES_UPPER_SNAKE_CASE

enum Foo { - firstValue = 0; + FIRST_VALUE = 0; - second_value = 1; + SECOND_VALUE = 1; }

ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH

enum Foo { - FOO_FIRST = 0; + FOO_UNSPECIFIED = 0; }

ENUM_NAMES_UPPER_CAMEL_CASE

- enum foobar { + enum FooBar { FIRST_VALUE = 0; SECOND_VALUE = 1; }

FIELD_NAMES_LOWER_SNAKE_CASE

message SongServerRequest { - required string SongName = 1; + required string song_name = 1; }

ИМПОРТ_СОРТИРОВКА

- import public "new.proto"; + import "myproject/other_protos.proto"; - import "myproject/other_protos.proto"; + import public "new.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/timestamp.proto";

MESSAGE_NAMES_UPPER_CAMEL_CASE

- message song_server_request { + message SongServerRequest { required string SongName = 1; required string song_name = 1; }

ЗАКАЗ

- option java_package = "com.example.foo"; - syntax = "proto3"; - package examplePb; - message song_server_request { } - import "other.proto"; + syntax = "proto3"; + package examplePb; + import "other.proto"; + option java_package = "com.example.foo"; + message song_server_request { }

PACKAGE_NAME_LOWER_CASE

- package myPackage + package my.package

RPC_NAMES_UPPER_CAMEL_CASE

service FooService { - rpc get_something(FooRequest) returns (FooResponse); + rpc GetSomething(FooRequest) returns (FooResponse); }

RPC_NAMES_UPPER_CAMEL_CASE

- service foo_service { + service FooService { rpc get_something(FooRequest) returns (FooResponse); rpc GetSomething(FooRequest) returns (FooResponse); }

ПОВТОРЯЕМЫЕ_НАЗВАНИЯ_ПОЛЕЙ_МНОЖЕСТВЕННО

- repeated string song_name = 1; + repeated string song_names = 1;

ОТСТУП

enum enumAllowingAlias { UNKNOWN = 0; - option allow_alias = true; + option allow_alias = true; STARTED = 1; - RUNNING = 2 [(custom_option) = "hello world"]; + RUNNING = 2 [(custom_option) = "hello world"]; - } +}
- message TestMessage { string test_field = 1; } + message TestMessage { + string test_field = 1; +}

ЦИТАТА_КОНСИСТЕНТНАЯ

option java_package = "com.example.foo"; - option go_package = 'example'; + option go_package = "example";

Создание собственных правил

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

Полный пример проекта (он же плагин) включен в этот репозиторий в каталоге _example/plugin .

Репортеры

protolint поставляется с несколькими встроенными репортерами (они же форматировщиками) для управления внешним видом результатов линтинга.

Вы можете указать репортера, используя флаг -reporter в командной строке. Например, -reporter junit использует репортер junit.

Встроенные параметры репортера:

  • простой (по умолчанию)
  • юнит
  • json
  • шариф
  • сонар (формат общего выпуска SonarQube)
  • юникс
  • tsc (совместим с компилятором TypeScript)

Настройка

Отключить правила в файле буфера протокола

Правила можно отключить с помощью комментария внутри файла Protocol Buffer в следующем формате. Правила будут отключены до конца файла или пока линтер не увидит соответствующий разрешающий комментарий:

// protolint:disable <ruleID1> [<ruleID2> <ruleID3>...] ... // protolint:enable <ruleID1> [<ruleID2> <ruleID3>...]

Также можно изменить команду отключения, добавив :next или :this, чтобы применить команду только к этой (текущей) или следующей строке соответственно.

Например:

enum Foo { // protolint:disable:next ENUM_FIELD_NAMES_UPPER_SNAKE_CASE firstValue = 0; // no error second_value = 1; // protolint:disable:this ENUM_FIELD_NAMES_UPPER_SNAKE_CASE THIRD_VALUE = 2; // spits out an error }

Установите параметр командной строки -auto_disable в next , this будут вставляться команды отключения при обнаружении проблем.

Вы можете указать опцию -fix вместе. Правила, поддерживающие auto_disable, подавляют нарушения, а не исправляют их, вызывающие несовместимость схемы.

Файл конфигурации

protolint может работать с использованием файла конфигурации с именем .protolint.yaml .

Спецификацию файла конфигурации см. в _example/config/.protolint.yaml .

protolint автоматически выполнит поиск текущего рабочего каталога для файла конфигурации по умолчанию и последующих родительских каталогов вплоть до корневого каталога файловой системы. И он может выполнять поиск в указанном каталоге с флагом -config_dir_path . Он также может выполнять поиск в указанном файле с флагом --config_path .

Коды выхода

При линтинге файлов protolint завершит работу с одним из следующих кодов завершения:

  • 0 : Линтинг прошел успешно, ошибок линтинга нет.
  • 1 : Линтинг прошел успешно, и обнаружена как минимум одна ошибка линтинга.
  • 2 : Линтинг не удался из-за всех остальных ошибок, таких как ошибки синтаксического анализа, внутренние ошибки и ошибки времени выполнения.

Мотивация

По состоянию на 20.12.2018 существуют аналогичные линтеры protobuf.

Один из них — плагин для компилятора Protocol Buffers от Google.

  • Если вы просто хотите линтинговать файлы, создание среды компиляции может оказаться утомительным.
  • И обычно на компиляцию файлов уходит гораздо больше времени, чем на их анализ.

Other — это инструмент командной строки, который также анализирует файлы буфера протокола.

  • Несмотря на то, что в нем есть много функций помимо линтера, он кажется громоздким для пользователей, которым нужен только линтер.
  • Правило «линта» склоняется к тому, чтобы быть упрямым.
  • Более того, набор правил и официальное руководство по стилю не соответствуют друг другу в точности. Требуется детально понять и правила, и руководство, а затем точно объединить правила.

Другие инструменты

17 декабря 2019 г. я написал статью, в которой сравнивал различные линтеры Protocol Buffer, включая protolint.

Зависимости

Разработка

Выпускать

Для упрощения процесса выпуска и уменьшения человеческих ошибок в репозиторий включен скрипт release.sh . Этот скрипт автоматизирует шаги, необходимые для создания и отправки нового тега выпуска.

Как использовать

Чтобы создать новый релиз, выполните следующую команду:

bash release.sh <version> [message]

Лицензия

Лицензия MIT (MIT)

Related MCP Servers

  • A
    security
    A
    license
    A
    quality
    dbt-mcp
    Last updated -
    16
    182
    Python
    Apache 2.0
    • Linux
    • Apple
  • A
    security
    A
    license
    A
    quality
    interactive-mcp
    Last updated -
    5
    705
    29
    TypeScript
    MIT License
    • Apple
    • Linux

View all related MCP servers

ID: n36s0xdbks