protolint-mcp

原林特

protolint 是用于协议缓冲区文件（proto2+proto3）的可插入式 linting/修复实用程序：

由于无需编译器，因此运行速度很快。
易于遵循官方风格指南。规则与风格指南完全对应。
- Fixer 会自动修复所有可能违反官方风格指南的行为。
允许使用协议缓冲区文件中的注释来禁用规则。
- 它对于必须保持 API 兼容性同时尽可能执行样式指南的项目很有用。
- 通过在发现的违规行为中插入评论，可以自动禁用某些规则。
加载插件以包含您的自定义 lint 规则。
已对所有规则进行测试。
许多集成支持。
- protoc插件
- 编辑器集成
- GitHub 动作
- CI 集成

演示

一旦 MCP 服务器配置完毕，您就可以要求任何 MCP 客户端（例如 Claude Desktop）对您的协议缓冲区文件进行 lint 和修复，如下所示：

此外，vim-protolint 的工作方式如下。

MCP 服务器

protolint 现在包括对模型上下文协议 (MCP)的支持，这使得 AI 模型可以直接与 protolint 交互。

用法

protolint --mcp

有关如何使用和集成 protolint 的 MCP 服务器功能的详细文档，请参阅MCP 文档。

安装

通过 Homebrew

可以使用 Homebrew 通过yoheimuta/protolint tap 在 Mac 或 Linux 上安装 protolint。

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 镜像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 中

您可以使用 nodejs 包管理器（如npm或yarn来使用protolint 。

$ npm install protolint --save-dev

这会将对开发依赖项的引用添加到您的本地package.json中。

安装过程中，会调用install.mjs脚本。它会从 GitHub 下载匹配的protolint 。与@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) 代理

在远程路径中，必须镜像来自发布页面的档案。

之后，您可以在 dev-scripts 中使用npx protolint （以及所有提供的 protolint 参数）。

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

您可以在package.json中添加一个protolint节点，该节点可能包含lint节点下方的protolint.yml的内容，即配置的根元素将是protolint 。

如果您想要获得与 TSC 编译器匹配的输出，请使用记者tsc 。

在 Python 项目中

你可以在 Python 项目中使用protolint作为 linter， pypi上的 wheel protolint-bin包含针对不同平台的预编译二进制文件。只需将所需版本添加到pyproject.toml或requirements.txt即可。

下载的wheels将包含protolint和protoc-gen-protolint的已编译Go二进制文件。您的平台必须与支持的二进制平台兼容。

您可以将 linter 配置添加到pyproject.toml中的tools.protolint包中。

用法

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-config.yaml中，即可使用 Go 运行 protolint：

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

编辑器集成

Visual Studio 代码

vscode-protolint

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

intellij-protolint

Vim（ ALE引擎）

ale的内置支持

Vim（ Syntastic ）

vim-protolint

GitHub 动作

GitHub Action用于在工作流程中运行 protolint

CI 集成

Jenkins 插件

warnings-ng以及任何使用violatons-lib 的

环境特定输出

您可以根据 CI/CD 环境的格式来格式化您的 linting。环境必须使用输出格式进行设置。目前，已实现以下输出：

环境	命令行值	描述	例子
Github Actions	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	ci-glab	从示例进行逆向工程	`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

用作协议插件

protolint 还维护了一个二进制文件protoc-gen-protolint ，它作为 protoc 插件执行 lint 功能。详情请参阅cmd/protoc-gen-protolint/README.md 。

这在您已经有 protoc 插件工作流程的情况下很有用。

从 Go 代码调用

你也可以在 Go 代码中使用 protolint。详情请参阅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，因为修复不会破坏它们的兼容性。您应该使用-fix运行 protolint。

官方的	可修复	自动禁用	ID	目的
是的	✅	✅	枚举字段名称前缀	验证枚举字段名称是否以其 ENUM_NAME_UPPER_SNAKE_CASE 作为前缀。
是的	✅	✅	枚举字段名称大写	验证所有枚举字段名称是否均为大写且带下划线。
是的	✅	✅	枚举字段名称为零值结尾	验证零值枚举是否应带有后缀（例如“UNSPECIFIED”、“INVALID”）。默认值为“UNSPECIFIED”。您可以使用`.protolint.yaml`配置具体的后缀。
是的	✅	✅	枚举名称大写驼峰格式	验证所有枚举名称是否都是 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`配置详细信息。
不	_	-	服务名称结束	强制服务名称使用一致的后缀。您可以使用`.protolint.yaml`配置特定的后缀。
不	_	-	FIELD_NAMES_EXCLUDE_PREPOSITIONS	验证所有字段名称不包含介词（例如“for”、“during”、“at”）。您可以使用`.protolint.yaml`配置特定的介词和排除的关键字。
不	_	-	消息名称不包括介词	验证所有消息名称不包含介词（例如“With”、“For”）。您可以使用`.protolint.yaml`配置特定的介词和排除的关键字。
不	_	-	RPC 名称大小写	验证所有 RPC 名称是否符合指定的约定。您需要使用`.protolint.yaml`配置特定的约定。
不	_	-	消息有评论	验证所有消息是否都有注释。您可以使用`.protolint.yaml`配置强制使用 Golang 风格的注释。
不	_	-	服务有评论	验证所有服务是否都有注释。您可以使用`.protolint.yaml`配置强制使用 Golang 风格的注释。
不	_	-	RPCS_HAVE_COMMENT	验证所有 rps 是否都有注释。你可以使用`.protolint.yaml`配置强制使用 Golang 风格的注释。
不	_	-	字段有评论	验证所有字段是否都有注释。你可以使用`.protolint.yaml`配置强制使用 Golang 风格的注释。
不	_	-	枚举有注释	验证所有枚举是否都有注释。你可以使用`.protolint.yaml`配置强制使用 Golang 风格的注释。
不	_	-	枚举字段有注释	验证所有枚举字段是否都有注释。你可以使用`.protolint.yaml`配置强制使用 Golang 风格的注释。
不	_	-	文件有注释	验证文件是否以文档注释开头。
不	_	-	语法一致	验证语法是否为指定版本。默认值为 proto3。您可以使用`.protolint.yaml`配置版本。

我建议您在.protolint.yaml中添加all_default: true ，因为上面的所有 linters 都会自动启用，以便您在 protolint 更新时始终可以享受最大的好处。

这里有一些示例，展示了默认启用的良好样式。- 是-不好的样式， +是一种好的样式：

枚举字段名称前缀

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

枚举字段名称大写

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

枚举字段名称为零值结尾

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

枚举名称大写驼峰格式

- 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 是可插入的 linter，因此您可以自由创建自定义 lint 规则。

完整的示例项目（又名插件）包含在_example/plugin目录下的此 repo 中。

记者

protolint 带有几个内置报告器（又名格式化程序）来控制 linting 结果的外观。

您可以在命令行中使用 -reporter 标志指定报告器。例如， -reporter junit会使用 junit 报告器。

内置的报告器选项有：

普通（默认）
Junit
json
萨里夫
sonar（SonarQube 通用问题格式）
unix
tsc（兼容 TypeScript 编译器）

配置

禁用协议缓冲区文件中的规则

可以使用 Protocol Buffer 文件中的注释禁用规则，注释格式如下。规则将一直处于禁用状态，直到文件末尾或 Linter 发现匹配的启用注释：

// 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标志搜索指定文件。

退出代码

在对文件进行 linting 时，protolint 将使用以下退出代码之一退出：

0 ：Linting 成功，并且没有 linting 错误。
1 ：Linting 成功，但至少有一个 linting 错误。
2 ：由于所有其他错误（例如解析、内部和运行时错误），Linting 失败。

动机

截至 2018 年 12 月 20 日，存在类似的 protobuf linters。

一个是Google的Protocol Buffers编译器的插件。

当您只想对文件进行 lint 时，创建编译环境可能会很繁琐。
并且编译文件通常比解析文件花费更多的时间。

另一个是命令行工具，它也可以检查协议缓冲区文件。

虽然它除了 lint 之外还有很多其他功能，但对于只想要 linter 的用户来说，它似乎很麻烦。
lint 规则倾向于固执己见。
另外，规则集和官方的风格指南并不完全对应，需要详细理解规则和指南，然后才能准确地结合规则。

其他工具

我于 2019/12/17 写了一篇比较各种 Protocol Buffer Linters（包括 protolint）的文章。

https://qiita.com/yoheimuta/items/da7678fcd046b93a2637
- 注意：这是用日语写的。

依赖项

go-protoparser

发展

发布

为了简化发布流程并减少人为错误，代码库中包含一个release.sh脚本。该脚本可自动执行创建和推送新发布标签所需的步骤。

如何使用

运行以下命令来创建新版本：

bash release.sh <version> [message]

执照

MIT 许可证（MIT）