プロトリント-MCP

プロトリント

protolint は、プロトコルバッファファイル (proto2+proto3) 用のプラグ可能な linting/fixing ユーティリティです。

コンパイラなしで動作するため、高速に実行されます。
公式スタイルガイドに従うのは簡単です。ルールとスタイルガイドは完全に一致しています。
- Fixer は、公式スタイルガイドの違反の可能性をすべて自動的に修正します。
プロトコルバッファファイル内のコメントを使用してルールを無効にすることができます。
- スタイルガイドを可能な限り適用しながら API の互換性を維持する必要があるプロジェクトに役立ちます。
- 発見された違反にコメントを挿入することで、一部のルールを自動的に無効にすることができます。
カスタム lint ルールを格納するプラグインを読み込みます。
すべてのルールのテストを実施しました。
多くの統合をサポートします。
- protocプラグイン
- エディター統合
- GitHubアクション
- CI統合

デモ

MCP サーバーが設定されると、Claude Desktop などの MCP クライアントに、次のようにしてプロトコルバッファーファイルを lint して修正するように要求できます。

また、vim-protolint は次のように動作します。

MCPサーバー

protolint には、モデルコンテキストプロトコル (MCP)のサポートが含まれるようになりました。これにより、AI モデルが protolint と直接対話できるようになります。

使用法

protolint --mcp

protolint の MCP サーバー機能の使用および統合方法の詳細については、 MCP ドキュメントを参照してください。

インストール

Homebrew経由

protolint は、yoheimuta/protolintタップ経由で Homebrew を使用して Mac または Linux にインストールできます。

brew tap yoheimuta/protolint
brew install protolint

homebrew-coreにはprotolint, brew install protolint.これはデフォルトでインストールされるデフォルトの tap です。こちらの方が簡単ですが、同じ作者によってメンテナンスされていません。最新の状態に保つには、まずbrew tap yoheimuta/protolintを実行することをお勧めします。

GitHubリリース経由

このリリースページからビルド済みのバイナリをダウンロードすることもできます。

https://github.com/yoheimuta/protolint/releases

各リリースのダウンロードセクションでは、.tar.gz パッケージ内のビルド済みバイナリを見つけることができます。

メンテナンスされたDockerイメージを使用する

protolint は、Docker ワークフローの一部として protolint を使用できるようにする Docker イメージyoheimuta/protolintを出荷します。

❯❯❯ 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内

npmやyarnなどの Node.js パッケージマネージャーを使用してprotolintを使用できます。

$ npm install protolint --save-dev

これにより、開発依存関係への参照がローカルのpackage.jsonに追加されます。

インストール中にinstall.mjsスクリプトが呼び出され、対応するprotolintをgithubからダウンロードします。 @electron/getと同様に、以下の環境変数を使用することでダウンロードを省略できます。

環境変数	デフォルト値	説明
PROTOLINT_MIRROR_HOST	https://github.com	バイナリをホストする HTTP/Web サーバーのベース URL
PROTOLINT_MIRROR_REMOTE_PATH	yoheimuta/protolint/ダウンロード/リリース	リモートホスト上のアーカイブへのパス
PROTOLINT_MIRROR_ユーザー名		HTTP 基本認証ユーザー名
PROTOLINT_MIRROR_パスワード		HTTP 基本認証パスワード
PROTOLINT_PROXY		オプションの認証データ付き HTTP(S) プロキシ

リモートパス内では、リリースページからのアーカイブをミラーリングする必要があります。

その後、開発スクリプト内でnpx protolint (提供されているすべての protolint 引数付き) を使用できます。

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

package.jsonにprotolintノードを追加できます。これには、 lintノードの下にprotolint.ymlの内容が含まれる場合があります。つまり、構成のルート要素はprotolintになります。

TSC コンパイラに一致する出力を取得する場合は、 reporter tscを使用します。

Pythonプロジェクト内

protolint Python プロジェクト内でリンターとして使用できます。pypiの wheel protolint-binには、様々なプラットフォーム向けにコンパイル済みのバイナリが含まれています。必要なバージョンをpyproject.tomlまたはrequirements.txtに追加するだけです。

ダウンロードしたホイールには、 protolintおよびprotoc-gen-protolint用のコンパイル済み Go バイナリが含まれます。お使いのプラットフォームは、サポートされているバイナリプラットフォームと互換性がある必要があります。

pyproject.tomlのtools.protolintパッケージに linter 設定を追加できます。

使用法

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 はコミット前のフックとして利用できます。Go で protolint を実行するには、リポジトリの.pre-commit-config.yamlに以下を追加してください。

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

または、これを使用して Docker で protolint を実行します。

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

エディター統合

ビジュアルスタジオコード

vscode-protolint

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

intellij-protolint

Vim（ ALEエンジン）

aleの組み込みサポート

Vim（シンタスティック）

vim-protolint

GitHubアクション

ワークフローで protolint を実行するためのGitHub Action

CI統合

Jenkinsプラグイン

warnings-ngおよびviolatons-lib を使用するもの

環境固有の出力

CI/CD環境のフォーマットに合わせてlintingをフォーマットすることが可能です。環境は出力フォーマットを使用して設定する必要があります。現在、以下の出力が実現されています。

環境	コマンドライン値	説明	例
Githubアクション	ci-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`
Azure DevOps	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/CD	シグラブ	例からリバースエンジニアリング	`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_STRING	1	Goテンプレートを含む文字列
PROTOLINT_CIREPORTER_TEMPLATE_FILE	2	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

protocプラグインとして使用する

protolint は、protoc プラグインとして lint 機能を実行するバイナリprotoc-gen-protolintも提供しています。詳細は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オプションを使用すると、修正可能なルールによって報告されたすべての問題を自動的に修正できます。修正可能な列については、以下を参照してください。

コマンドラインの-auto_disableオプションを使用すると、自動無効化ルールによって報告されたすべての問題を自動的に無効化できます。この機能は、既存の違反を修正すると互換性が損なわれる場合に役立ちます。以下の AutoDisable 列を参照してください。

*1: これらのルールは、修正によって互換性が損なわれることはないため、AutoDisable をサポートしていないはずです。protolint を-fix付きで実行してください。

正式	修正可能	自動無効化	ID	目的
はい	✅	✅	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 (先頭が大文字) であることを確認します。
はい	✅	*1	ファイル名の小文字表記	すべてのファイル名がlower_snake_case.protoであることを確認します。除外するファイルは`.protolint.yaml`で設定できます。
はい	✅	✅	フィールド名_小文字_スネークケース	すべてのフィールド名がアンダースコアで区切られた名前であることを確認します。
はい	✅	*1	インポートソート済み	すべてのインポートがソートされていることを確認します。
はい	✅	✅	メッセージ名_大文字_キャメルケース	すべてのメッセージ名が CamelCase (先頭が大文字) であることを確認します。
はい	✅	*1	注文	すべてのファイルが特定の方法で順序付けられていることを確認します。
はい	✅	*1	パッケージ名小文字	パッケージ名には小文字のみが含まれていることを確認します。
はい	✅	✅	RPC_NAMES_UPPER_CAMEL_CASE	すべての rpc 名が CamelCase (先頭が大文字) であることを確認します。
はい	✅	✅	サービス名_大文字_キャメルケース	すべてのサービス名が CamelCase (先頭が大文字) であることを確認します。
はい	✅	✅	繰り返しフィールド名複数形	繰り返されるフィールド名が複数形の名前であることを確認します。
はい	✅	*1	引用符の一貫性	文字列の引用符の使用が一貫しているかどうかを検証します。デフォルトは二重引用符です`.protolint.yaml`で特定の引用符を設定できます。
はい	✅	*1	インデント	一貫したインデントスタイルを強制します。デフォルトのスタイルは2スペースです。適切な改行の挿入もデフォルトで強制されます。詳細は`.protolint.yaml`で設定できます。
はい	✅	*1	PROTO3_FIELDS_AVOID_REQUIRED	proto3 ではすべてのフィールドが必須にならないことを確認します。
はい	_	✅	PROTO3_GROUPS_AVOID	proto3 ではすべてのグループを回避する必要があることを確認します。
はい	_	*1	最大行長	行の最大長を強制します。行の長さは、行に含まれるUnicode文字数として定義されます。デフォルトは80文字です。詳細は`.protolint.yaml`で設定できます。
いいえ	_	-	サービス名_END_WITH	サービス名に一貫したサフィックスを適用します`.protolint.yaml`で特定のサフィックスを設定できます。
いいえ	_	-	フィールド名の前置詞を除外する	すべてのフィールド名に前置詞（例：「for」、「during」、「at」）が含まれていないことを確認します。特定の前置詞と除外キーワードは`.protolint.yaml`で設定できます。
いいえ	_	-	メッセージ名に前置詞が含まれていない	すべてのメッセージ名に前置詞（例："With"、"For"）が含まれていないことを確認します。特定の前置詞と除外キーワードは`.protolint.yaml`で設定できます。
いいえ	_	-	RPC_NAMES_CASE	すべてのRPC名が指定された規則に準拠しているかどうかを検証します。特定の規則は`.protolint.yaml`で設定する必要があります。
いいえ	_	-	メッセージにコメントあり	すべてのメッセージにコメントがあるかどうかを検証します`.protolint.yaml`でGolangスタイルのコメントを強制するように設定できます。
いいえ	_	-	サービスにコメントあり	すべてのサービスにコメントがあることを確認します`.protolint.yaml`でGo言語スタイルのコメントを強制するように設定できます。
いいえ	_	-	RPCS_コメントあり	すべての rps にコメントがあるかどうかを検証します`.protolint.yaml`で Golang スタイルのコメントを強制するように設定できます。
いいえ	_	-	FIELDS_HAVE_COMMENT	すべてのフィールドにコメントがあるかどうかを検証します`.protolint.yaml`でGolangスタイルのコメントを強制するように設定できます。
いいえ	_	-	ENUMS_HAVE_COMMENT	すべての列挙型にコメントがあるかどうかを検証します`.protolint.yaml`でGolangスタイルのコメントを強制するように設定できます。
いいえ	_	-	ENUM_FIELDS_HAVE_COMMENT	すべての列挙型フィールドにコメントがあるかどうかを検証します`.protolint.yaml`でGolangスタイルのコメントを強制するように設定できます。
いいえ	_	-	ファイルにコメントがある	ファイルがドキュメントコメントで始まっていることを確認します。
いいえ	_	-	構文の一貫性	構文が指定されたバージョンであることを確認します。デフォルトはproto3です。バージョンは`.protolint.yaml`で設定できます。

.protolint.yamlにall_default: trueを追加することをお勧めします。これにより、上記のすべてのリンターが自動的に有効になり、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;
}

フィールド名_小文字_スネークケース

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 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 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 は、カスタム lint ルールを自由に作成できるプラグイン可能なリンターです。

完全なサンプルプロジェクト (プラグインとも呼ばれます) は、このリポジトリの_example/pluginディレクトリに含まれています。

記者

protolint には、リンティング結果の外観を制御するためのいくつかの組み込みレポーター (別名フォーマッタ) が付属しています。

コマンドラインで -reporter フラグを使用してレポーターを指定できます。例えば、 -reporter junit junit レポーターを使用します。

組み込みのレポーターオプションは次のとおりです。

プレーン（デフォルト）
ジュニット
JSON
サリフ
sonar (SonarQube 汎用発行フォーマット)
Unix
tsc (TypeScript コンパイラと互換性あり)

設定

プロトコルバッファファイル内のルールを無効にする

ルールは、プロトコルバッファファイル内に以下の形式のコメントを記述することで無効化できます。ルールは、ファイルの最後まで、またはリンターが対応する有効化コメントを見つけるまで無効化されます。

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

また、:next または :this を追加して、disable コマンドを変更し、それぞれこの行 (現在行) または次の行にのみコマンドを適用することもできます。

例えば：

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に設定すると、問題が発見されるたびに、disable コマンドが挿入されます。

-fixオプションも一緒に指定できます。auto_disable をサポートするルールは、スキーマの非互換性を引き起こす違反を修正するのではなく、抑制します。

設定ファイル

protolint は、 .protolint.yamlという名前の設定ファイルを使用して動作できます。

設定ファイルの仕様については、 _example/config/.protolint.yamlを参照してください。

protolint は、デフォルトで現在の作業ディレクトリから設定ファイルを自動的に検索し、ファイルシステムのルートディレクトリまでの親ディレクトリも検索します。 -config_dir_pathフラグを指定すると、指定したディレクトリを検索できます。また、 --config_pathフラグを指定すると、指定したファイルを検索できます。

終了コード

ファイルを lint する場合、protolint は次のいずれかの終了コードで終了します。

0 : リンティングは成功し、リンティングエラーはありません。
1 : リンティングは成功しましたが、少なくとも 1 つのリンティングエラーがあります。
2 : 解析エラー、内部エラー、実行時エラーなど、その他のすべてのエラーが原因で、リンティングは失敗しました。

モチベーション

2018/12/20現在、同様のprotobufリンターが存在します。

1 つは、Google の Protocol Buffers コンパイラ用のプラグインです。

単にファイルを lint したいだけの場合は、コンパイル環境を作成するのは面倒な場合があります。
また、一般的に、ファイルを解析するよりも、ファイルをコンパイルする方が時間がかかります。

Other は、Protocol Buffer ファイルの lint も実行するコマンドラインツールです。

リント以外の機能も多数ありますが、リント機能だけが必要なユーザーにとっては面倒なようです。
リントルールは、意見を主張する傾向があります。
さらに、ルールセットと公式スタイルガイドは完全には一致していません。ルールとガイドの両方を詳細に理解した上で、ルールを正確に組み合わせる必要があります。

その他のツール

2019/12/17にprotolintを含む各種Protocol Buffer Linterを比較した記事を書きました。

https://qiita.com/yoheimuta/items/da7678fcd046b93a2637
- 注: これは日本語で書かれています。

依存関係

go-protoparser

発達

リリース

リリースプロセスを効率化し、人的エラーを削減するために、リポジトリにはrelease.shスクリプトが含まれています。このスクリプトは、新しいリリースタグの作成とプッシュに必要な手順を自動化します。

使い方

新しいリリースを作成するには、次のコマンドを実行します。

bash release.sh <version> [message]

ライセンス

MITライセンス（MIT）

protolint-mcp

Integrations