DOCSEARCHbyAlgolia
Submit Docs

protolint

repository·master·Indexed 20 days ago

https://github.com/yoheimuta/protolint

A fast, pluggable linter and fixer for Protocol Buffer files (proto2 and proto3) that enforces style guides without requiring a compiler. It includes a protoc plugin (protoc-gen-protolint), support for custom Go-based plugins via hashicorp/go-plugin, and an MCP server mode for integration with AI assistants like Claude Desktop.

Tokens
12.5K
Snippets
46
Records
66
Agent score
66%

What's inside protolint

  1. What is protolint

    master

    protolint is a pluggable linting and fixing utility for Protocol Buffer files (supporting both proto2 and proto3). It is designed to be fast by operating without a compiler and provides a direct mapping to the official Protocol Buffer style guide.

    Key features include:

    • Automatic Fixing: A fixer that automatically corrects violations of the official style guide.
    • Rule Disabling: Ability to disable specific rules using comments within .proto files, which is useful for maintaining API compatibility.
    • Extensibility: Supports loading plugins for custom lint rules.
    • Integrations: Supports protoc plugin, editor integrations, GitHub Actions, and CI environments.

  2. Understand protolint rules and style guides

    master

    protolint enforces two types of rule sets:

    1. Official Style Guide: Enabled by default. These rules follow the official Protobuf programming guides. Many of these rules are fixable using the -fix command-line option.
    2. Unofficial Style Guide: Disabled by default. You can enable specific rules from this set by configuring them in your .protolint.yaml file.

    To ensure you always benefit from new linting improvements as protolint is updated, it is recommended to add all_default: true to your .protolint.yaml configuration.

  4. Disable rules in Protocol Buffer files

    master

    You can suppress specific linting rules within your .proto files using special comments. Rules remain disabled until the end of the file or until an enable comment is encountered.

    Standard Disable/Enable

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

    Scoped Commands

    You can limit the scope of a disable command by appending :next or :this:

    • :next: Applies the command to the very next line.
    • :this: Applies the command only to the current line.

    Automatic Disabling

    Use the -auto_disable flag with the values next or this to have protolint automatically insert these comments when it detects violations. If used with the -fix option, rules that support auto_disable will suppress the violation instead of attempting a fix that might cause schema incompatibility.

    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
}

  6. Configure proto_root for protolint

    master

    When using protoc --proto_path to point to a specific directory, protolint might fail to locate the files. To fix this, use the proto_root option within --protolint_opt to explicitly tell the plugin the root directory of your proto files.

    # Example: Telling protolint the root is 'protos'
protoc \
    --proto_path=protos \
    --protolint_out=. \
    --protolint_opt=proto_root=protos \
    helloworld.proto

  7. Run a protolint plugin

    master

    To use a custom plugin with protolint, use the -plugin flag followed by the path to the plugin executable. You can also pass specific flags directly to the plugin within the same argument.

    Requirements:

    • sh must be available in your PATH.
    • Ensure your .protolint.yaml configuration does not conflict with or disable your plugin.

    Commands:

    To run linting with a plugin:

    protolint -plugin ./plugin_example /path/to/files

    To run linting with specific flags passed to the plugin:

    protolint -plugin "./plugin_example -go_style=false" /path/to/files

    To verify that your plugin is loaded correctly by protolint:

    protolint list -plugin ./plugin_example

  8. Create custom protolint rules

    master
    protolint is a pluggable linter, allowing you to create and implement your own custom lint rules. A complete sample project demonstrating how to build a plugin is located in the _example/plugin directory of this repository.

  9. Produce multiple outputs for CI/CD and static analysis tools

    master

    You can generate output for your CI/CD environment while simultaneously creating an output file for static code analysis tools like GitHub CodeQL or SonarQube by using the --add-reporter flag.

    The value for --add-reporter must follow the format <reporter-name>:<output-file-path> (without angle brackets).

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

  12. Use protoc-gen-protolint with protoc

    master

    Run the linter through protoc using the --protolint_out flag. All flags supported by the underlying protolint tool must be passed as a comma-separated string via the --protolint_opt option.

    # Basic usage
protoc --protolint_out=. *.proto

# Usage with options (comma-separated)
protoc \
    --protolint_out=. \
    --protolint_opt=v,fix,config_dir_path=_example/config,reporter=junit,plugin=./plugin_example \
    *.proto