プロトリント
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 サーバー機能の使用および統合方法の詳細については、 MCP ドキュメントを参照してください。
インストール
Homebrew経由
protolint は、yoheimuta/protolintタップ経由で Homebrew を使用して Mac または Linux にインストールできます。
homebrew-coreにはprotolint,
brew install protolint.
これはデフォルトでインストールされるデフォルトの tap です。こちらの方が簡単ですが、同じ作者によってメンテナンスされていません。最新の状態に保つには、まずbrew tap yoheimuta/protolint
を実行することをお勧めします。
GitHubリリース経由
このリリース ページからビルド済みのバイナリをダウンロードすることもできます。
各リリースのダウンロード セクションでは、.tar.gz パッケージ内のビルド済みバイナリを見つけることができます。
メンテナンスされたDockerイメージを使用する
protolint は、Docker ワークフローの一部として protolint を使用できるようにする Docker イメージyoheimuta/protolintを出荷します。
ソースから
Goが利用可能な場合は、ソースからバイナリをインストールできます。ただし、バージョン情報が含まれていないため、代わりにビルド済みのバイナリを使用することをお勧めします。
JavaScript / TypeScript内
npm
やyarn
などの Node.js パッケージ マネージャーを使用してprotolint
を使用できます。
これにより、開発依存関係への参照がローカルのpackage.json
に追加されます。
インストール中にinstall.mjsスクリプトが呼び出され、対応するprotolint
をgithubからダウンロードします。 @electron/getと同様に、以下の環境変数を使用することでダウンロードを省略できます。
環境変数 | デフォルト値 | 説明 |
PROTOLINT_MIRROR_HOST | バイナリをホストする HTTP/Web サーバーのベース URL | |
PROTOLINT_MIRROR_REMOTE_PATH | yoheimuta/protolint/ダウンロード/リリース | リモートホスト上のアーカイブへのパス |
PROTOLINT_MIRROR_ユーザー名 | HTTP 基本認証ユーザー名 | |
PROTOLINT_MIRROR_パスワード | HTTP 基本認証パスワード | |
PROTOLINT_PROXY | オプションの認証データ付き HTTP(S) プロキシ |
リモート パス内では、リリースページからのアーカイブをミラーリングする必要があります。
その後、開発スクリプト内でnpx protolint
(提供されているすべての 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 はデフォルトでは設定を必要とせず、ほとんどのプロジェクトではそのまま使用できるはずです。
バージョン管理統合
protolint はコミット前のフックとして利用できます。Go で protolint を実行するには、リポジトリの.pre-commit-config.yaml
に以下���追加してください。
または、これを使用して Docker で protolint を実行します。
エディター統合
ビジュアルスタジオコード
JetBrains IntelliJ IDEA、GoLand、WebStorm、PHPStorm、PyCharm...
Vim( ALEエンジン)
Vim(シンタスティック)
GitHubアクション
ワークフローで protolint を実行するためのGitHub Action
CI統合
Jenkinsプラグイン
warnings-ngおよびviolatons-lib を使用するもの
環境固有の出力
CI/CD環境のフォーマットに合わせてlintingをフォーマットすることが可能です。環境は出力フォーマットを使用して設定する必要があります。現在、以下の出力が実現されています。
環境 | コマンドライン値 | 説明 | 例 |
Githubアクション | ci-gh |
| |
Azure DevOps | ci-az |
| |
Gitlab CI/CD | シグラブ | 例からリバースエンジニアリング |
|
汎用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>
( <
と>
を省略)の形式で指定する必要があることに注意してください。
protocプラグインとして使用する
protolint は、protoc プラグインとして lint 機能を実行するバイナリprotoc-gen-protolintも提供しています。詳細はcmd/protoc-gen-protolint/README.mdをご覧ください。
これは、すでに protoc プラグイン ワークフローがある場合に役立ちます。
Goコードからの呼び出し
protolint は Go コードからも使用できます。詳しくはGo ドキュメントとlib/lint_test.go をご覧ください。
ルール
詳細については、 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"です
で特定のサフィックスを設定できます。 |
はい | ✅ | ✅ | ENUM_NAMES_UPPER_CAMEL_CASE | すべての列挙名が CamelCase (先頭が大文字) であることを確認します。 |
はい | ✅ | *1 | ファイル名の小文字表記 | すべてのファイル名がlower_snake_case.protoであることを確認します。除外するファイルは
で設定できます。 |
はい | ✅ | ✅ | フィールド名_小文字_スネークケース | すべてのフィールド名がアンダースコアで区切られた名前であることを確認します。 |
はい | ✅ | *1 | インポートソート済み | すべてのインポートがソートされていることを確認します。 |
はい | ✅ | ✅ | メッセージ名_大文字_キャメルケース | すべてのメッセージ名が CamelCase (先頭が大文字) であることを確認します。 |
はい | ✅ | *1 | 注文 | すべてのファイルが特定の方法で順序付けられていることを確認します。 |
はい | ✅ | *1 | パッケージ名小文字 | パッケージ名には小文字のみが含まれていることを確認します。 |
はい | ✅ | ✅ | RPC_NAMES_UPPER_CAMEL_CASE | すべての rpc 名が CamelCase (先頭が大文字) であることを確認します。 |
はい | ✅ | ✅ | サービス名_大文字_キャメルケース | すべてのサービス名が CamelCase (先頭が大文字) であることを確認します。 |
はい | ✅ | ✅ | 繰り返しフィールド名複数形 | 繰り返されるフィールド名が複数形の名前であることを確認します。 |
はい | ✅ | *1 | 引用符の一貫性 | 文字列の引用符の使用が一貫しているかどうかを検証します。デフォルトは二重引用符です
で特定の引用符を設定できます。 |
はい | ✅ | *1 | インデント | 一貫したインデントスタイルを強制します。デフォルトのスタイルは2スペースです。適切な改行の挿入もデフォルトで強制されます。詳細は
で設定できます。 |
はい | ✅ | *1 | PROTO3_FIELDS_AVOID_REQUIRED | proto3 ではすべてのフィールドが必須にならないことを確認します。 |
はい | _ | ✅ | PROTO3_GROUPS_AVOID | proto3 ではすべてのグループを回避する必要があることを確認します。 |
はい | _ | *1 | 最大行長 | 行の最大長を強制します。行の長さは、行に含まれるUnicode文字数として定義されます。デフォルトは80文字です。詳細は
で設定できます。 |
いいえ | _ | - | サービス名_END_WITH | サービス名に一貫したサフィックスを適用します
で特定のサフィックスを設定できます。 |
いいえ | _ | - | フィールド名の前置詞を除外する | すべてのフィールド名に前置詞(例:「for」、「during」、「at」)が含まれていないことを確認します。特定の前置詞と除外キーワードは
で設定できます。 |
いいえ | _ | - | メッセージ名に前置詞が含まれていない | すべてのメッセージ名に前置詞(例:"With"、"For")が含まれていないことを確認します。特定の前置詞と除外キーワードは
で設定できます。 |
いいえ | _ | - | RPC_NAMES_CASE | すべてのRPC名が指定された規則に準拠しているかどうかを検証します。特定の規則は
で設定する必要があります。 |
いいえ | _ | - | メッセージにコメントあり | すべてのメッセージにコメントがあるかどうかを検証します
でGolangスタイルのコメントを強制するように設定できます。 |
いいえ | _ | - | サービスにコメントあり | すべてのサービスにコメントがあることを確認します
でGo言語スタイルのコメントを強制するように設定できます。 |
いいえ | _ | - | RPCS_コメントあり | すべての rps にコメントがあるかどうかを検証します
で Golang スタイルのコメントを強制するように設定できます。 |
いいえ | _ | - | FIELDS_HAVE_COMMENT | すべてのフィールドにコメントがあるかどうかを検証します
でGolangスタイルのコメントを強制するように設定できます。 |
いいえ | _ | - | ENUMS_HAVE_COMMENT | すべての列挙型にコメントがあるかどうかを検証します
でGolangスタイルのコメントを強制するように設定できます。 |
いいえ | _ | - | ENUM_FIELDS_HAVE_COMMENT | すべての列挙型フィールドにコメントがあるかどうかを検証します
でGolangスタイルのコメントを強制するように設定できます。 |
いいえ | _ | - | ファイルにコメントがある | ファイルがドキュメントコメントで始まっていることを確認します。 |
いいえ | _ | - | 構文の一貫性 | 構文が指定されたバージョンであることを確認します。デフォルトはproto3です。バージョンは
で設定できます。 |
上記のすべてのリンターが自動的に有効になり、protolint が更新されるたびに常に最大限のメリットを享受できるため、 .protolint.yaml
にall_default: true
を追加することをお勧めします。
デフォルトで有効になっている適切なスタイルを示す例をいくつか示します。 -
は不適切なスタイル、 +
は適切なスタイルです。
ENUM_FIELD_NAMES_PREFIX
ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
ENUM_NAMES_UPPER_CAMEL_CASE
フィールド名_小文字_スネークケース
インポートソート
メッセージ名_大文字_キャメルケース
注文
パッケージ名小文字
RPC_NAMES_UPPER_CAMEL_CASE
RPC_NAMES_UPPER_CAMEL_CASE
繰り返しフィールド名複数形
インデント
引用符の一貫性
カスタムルールの作成
protolint は、カスタム lint ルールを自由に作成できるプラグイン可能なリンターです。
完全なサンプル プロジェクト (プラグインとも呼ばれます) は、このリポジトリの_example/pluginディレクトリに含まれています。
記者
protolint には、リンティング結果の外観を制御するためのいくつかの組み込みレポーター (別名フォーマッタ) が付属しています。
コマンドラインで -reporter フラグを使用してレポーターを指定できます。例えば、 -reporter junit
junit レポーターを使用します。
組み込みのレポーター オプションは次のとおりです。
プレーン(デフォルト)
ジュニット
JSON
サリフ
sonar (SonarQube 汎用発行フォーマット)
Unix
tsc (TypeScript コンパイラと互換性あり)
設定
プロトコルバッファファイル内のルールを無効にする
ルールは、プロトコルバッファファイル内に以下の形式のコメントを記述することで無効化できます。ルールは、ファイルの最後まで、またはリンターが対応する有効化コメントを見つけるまで無効化されます。
また、:next または :this を追加して、disable コマンドを変更し、それぞれこの行 (現在行) または次の行にのみコマンドを適用することもできます。
例えば:
コマンドライン オプション-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
注: これは日本語で書かれています。
依存関係
発達
リリース
リリースプロセスを効率化し、人的エラーを削減するために、リポジトリにはrelease.sh
スクリプトが含まれています。このスクリプトは、新しいリリースタグの作成とプッシュに必要な手順を自動化します。
使い方
新しいリリースを作成するには、次のコマンドを実行します。
ライセンス
MITライセンス(MIT)
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
プロトリント-MCP
Related MCP Servers
- MIT License
- MIT License
- MIT License