Protolint

https://github.com/yoheimuta/protolint
Admin
Protolint is a pluggable linting and fixing utility for Protocol Buffer files that enforces style...
Tokens:15,034
Snippets:199
Trust Score:8.2
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install from Source

Source: https://github.com/yoheimuta/protolint/blob/master/cmd/protoc-gen-protolint/README.md

Install the binary directly from the GitHub repository using Go.

```bash
go get -u -v github.com/yoheimuta/protolint/cmd/protoc-gen-protolint
```

--------------------------------

### Install via Homebrew

Source: https://github.com/yoheimuta/protolint/blob/master/cmd/protoc-gen-protolint/README.md

Use Homebrew to install the protolint binary on macOS or Linux.

```bash
brew tap yoheimuta/protolint
brew install protolint
```

--------------------------------

### Install Protolint from Source

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Install the protolint binary from source using Go. This method is an alternative to pre-built binaries, though it may not include version information.

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

--------------------------------

### Start Protolint MCP Server

Source: https://context7.com/yoheimuta/protolint/llms.txt

Command to start protolint in Model Context Protocol (MCP) server mode for AI assistant integration.

```bash
# Start MCP server mode
protolint --mcp
```

--------------------------------

### Starting Protolint in MCP Server Mode

Source: https://github.com/yoheimuta/protolint/blob/master/mcp/README.md

Command to start protolint as an MCP server, which listens for commands via stdin and writes responses to stdout.

```APIDOC
## Starting Protolint in MCP Server Mode

### Description
Starts protolint as an MCP server. It listens for commands via standard input (stdin) and writes responses to standard output (stdout).

### Command
```sh
protolint --mcp
```
```

--------------------------------

### Protolint npm script example

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Example of how to integrate protolint into your npm scripts within package.json. The 'preprotoc' script demonstrates running protolint before a protoc command.

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

--------------------------------

### Install Protolint via npm

Source: https://context7.com/yoheimuta/protolint/llms.txt

Commands to install the protolint package as a development dependency.

```bash
# Install as dev dependency
npm install protolint --save-dev

# Or with yarn
yarn add -D protolint
```

--------------------------------

### Start protolint in MCP server mode

Source: https://github.com/yoheimuta/protolint/blob/master/mcp/README.md

Execute this command to launch the server, which communicates via standard input and output.

```sh
protolint --mcp
```

--------------------------------

### Protolint CLI Usage Examples

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Demonstrates various ways to use the protolint command-line interface for linting Protocol Buffer files. Includes options for file mode, directory mode, configuration paths, fixing issues, and output reporters.

```sh
protolint lint example.proto example2.proto # file mode, specify multiple specific files
```

```sh
protolint lint .                            # directory mode, search for all .proto files recursively
```

```sh
protolint .                                 # same as "protolint lint ."
```

```sh
protolint lint -config_path=path/to/your_protolint.yaml . # use path/to/your_protolint.yaml
```

```sh
protolint lint -config_dir_path=path/to .   # search path/to for .protolint.yaml
```

```sh
protolint lint -fix .                       # automatically fix some of the problems reported by some rules
```

```sh
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.
```

```sh
protolint lint -auto_disable=next .         # automatically insert disable comments to the other problems. 
```

```sh
protolint lint -v .                         # with verbose output to investigate the parsing error
```

```sh
protolint lint -no-error-on-unmatched-pattern . # exits with success code even if no file is found (file & directory mode)
```

```sh
protolint lint -reporter junit .            # output results in JUnit XML format
```

```sh
protolint lint -output_file=path/to/out.txt # output results to path/to/out.txt
```

```sh
protolint lint -plugin ./my_custom_rule1 -plugin ./my_custom_rule2 .   # run custom lint rules.
```

```sh
protolint list                              # list all current lint rules being used
```

```sh
protolint version                           # print protolint version
```

```sh
protolint --version                         # print protolint version (global flag)
```

```sh
protolint -v                                # print protolint version (when used as the only argument)
```

--------------------------------

### Configure Protolint in package.json

Source: https://context7.com/yoheimuta/protolint/llms.txt

Example configuration for npm scripts and linting rules within package.json.

```json
{
  "scripts": {
    "lint:proto": "npx protolint lint proto/",
    "lint:proto:fix": "npx protolint lint -fix proto/",
    "preprotoc": "npx protolint lint proto/"
  },
  "protolint": {
    "lint": {
      "rules": {
        "all_default": true
      },
      "rules_option": {
        "indent": {
          "style": 2
        }
      }
    }
  }
}
```

--------------------------------

### Install Protolint with npm

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Install protolint as a development dependency in your Node.js project using npm. This command adds protolint to your package.json.

```sh
npm install protolint --save-dev
```

--------------------------------

### Check Protolint Version

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use 'protolint version', '--version', or '-v' (as a standalone argument) to display the installed protolint version.

```bash
protolint version
```

```bash
protolint --version
```

```bash
protolint -v
```

--------------------------------

### Example prompt for Claude Desktop

Source: https://github.com/yoheimuta/protolint/blob/master/mcp/README.md

Natural language request to trigger the linting process within the Claude Desktop interface.

```text
Can you lint my protocol buffer files /path/to/file1.proto and /path/to/file2.proto?
```

--------------------------------

### Check plugin version

Source: https://github.com/yoheimuta/protolint/blob/master/cmd/protoc-gen-protolint/README.md

Verify the installed version of the protoc-gen-protolint plugin.

```bash
protoc-gen-protolint version
```

--------------------------------

### Response from lint-files tool

Source: https://github.com/yoheimuta/protolint/blob/master/mcp/README.md

Example JSON-RPC response containing the linting results for the requested files.

```json
{
  "jsonrpc": "2.0",
  "id": "request-1234",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"exit_code\":0,\"results\":[{\"file_path\":\"/path/to/file1.proto\",\"failures\":[{\"rule_id\":\"ENUM_NAMES_UPPER_CAMEL_CASE\",\"message\":\"Enum name must be UpperCamelCase\",\"line\":5,\"column\":6,\"severity\":\"error\"}]}]}"
      }
    ],
    "isError": false
  }
}
```

--------------------------------

### Request lint-files tool call

Source: https://github.com/yoheimuta/protolint/blob/master/mcp/README.md

Example JSON-RPC request to invoke the lint-files tool with specific file paths and configuration options.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": "request-1234",
  "params": {
    "name": "lint-files",
    "arguments": {
      "files": ["/path/to/file1.proto", "/path/to/file2.proto"],
      "config_path": "/path/to/config.yaml",
      "fix": true
    }
  }
}
```

--------------------------------

### JSON Reporter Output Format

Source: https://context7.com/yoheimuta/protolint/llms.txt

Example of the structured JSON output generated by the reporter.

```json
{
  "basedir": "/path/to/project",
  "lints": [
    {
      "filename": "proto/service.proto",
      "line": 10,
      "column": 5,
      "message": "Enum name \"status\" must be UpperCamelCase",
      "rule": "ENUM_NAMES_UPPER_CAMEL_CASE",
      "severity": "error"
    },
    {
      "filename": "proto/service.proto",
      "line": 15,
      "column": 3,
      "message": "Field name \"UserName\" must be underscore_separated_names",
      "rule": "FIELD_NAMES_LOWER_SNAKE_CASE",
      "severity": "warning"
    }
  ]
}
```

--------------------------------

### Auto-Fix Protocol Buffer Violations

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use the '-fix' flag to automatically correct style guide violations in Protocol Buffer files. This is useful for maintaining code quality.

```bash
protolint lint -fix .
```

--------------------------------

### Basic Protoc Plugin Usage

Source: https://context7.com/yoheimuta/protolint/llms.txt

Demonstrates basic and advanced usage of protolint as a protoc plugin, including applying options and integrating custom plugins.

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

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

# With custom plugins
protoc \
    --protolint_out=. \
    --protolint_opt=plugin=./my_custom_rule \
    *.proto

# Check version
protoc-gen-protolint version
```

--------------------------------

### Build and Run Custom Protolint Plugin

Source: https://context7.com/yoheimuta/protolint/llms.txt

Commands to build a custom protolint plugin as a Go binary and then run protolint with the plugin, including passing custom flags and verifying its loading.

```bash
# Build the plugin as a normal Go binary
go build -o my_plugin main.go

# Run protolint with the custom plugin
protolint -plugin ./my_plugin /path/to/protos

# Pass flags to your plugin
protolint -plugin "./my_plugin -go_style=false" /path/to/protos

# Verify plugin is loaded
protolint list -plugin ./my_plugin
```

--------------------------------

### Lint All Protocol Buffer Files Recursively

Source: https://context7.com/yoheimuta/protolint/llms.txt

Run 'protolint lint .' to lint all .proto files in the current directory and its subdirectories. This is a common shorthand for linting an entire project.

```bash
protolint lint .
```

```bash
protolint .
```

--------------------------------

### List All Available Lint Rules

Source: https://context7.com/yoheimuta/protolint/llms.txt

Run 'protolint list' to display all lint rules that protolint currently supports.

```bash
protolint list
```

--------------------------------

### List Rules Including Custom Plugins

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use 'protolint list -plugin' followed by the path to a custom plugin to list rules from both built-in and custom sources.

```bash
protolint list -plugin ./my_custom_rule
```

--------------------------------

### Run protoc with protolint

Source: https://github.com/yoheimuta/protolint/blob/master/cmd/protoc-gen-protolint/README.md

Basic command to execute the protolint plugin via protoc.

```bash
protoc --protolint_out=. *.proto
```

--------------------------------

### Build a Protolint Plugin

Source: https://github.com/yoheimuta/protolint/blob/master/_example/plugin/README.md

Compile the plugin source code into an executable binary.

```bash
go build -o plugin_example main.go
```

--------------------------------

### Protoc Plugin with Proto Path Option

Source: https://context7.com/yoheimuta/protolint/llms.txt

Shows how to configure protolint's proto_root option when using protoc's --proto_path for nested proto structures.

```bash
# When using --proto_path, specify proto_root
protoc \
    --proto_path=protos \
    --protolint_out=. \
    --protolint_opt=proto_root=protos \
    helloworld.proto
```

--------------------------------

### Configure plugin options

Source: https://github.com/yoheimuta/protolint/blob/master/cmd/protoc-gen-protolint/README.md

Pass multiple flags to the plugin using the --protolint_opt argument.

```bash
protoc \
    --protolint_out=. \
    --protolint_opt=v,fix,config_dir_path=_example/config,reporter=junit,plugin=./plugin_example \
    *.proto
```

--------------------------------

### Run Protolint with Docker

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Execute protolint using its maintained Docker image. Mount your current directory as a volume and set the working directory to the workspace for linting proto files.

```docker
docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint _example/proto
```

--------------------------------

### Run a Protolint Plugin

Source: https://github.com/yoheimuta/protolint/blob/master/_example/plugin/README.md

Execute the protolint tool with a custom plugin, optionally passing flags to the plugin or listing loaded plugins.

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

# Or you can pass some flags to your plugin:
protolint -plugin "./plugin_example -go_style=false" /path/to/files

# You can see that your plugin is loaded correctly.
protolint list -plugin ./plugin_example
```

--------------------------------

### Configure Protolint with a Config File

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Protolint can be configured using a `.protolint.yaml` file. This file specifies rules, reporters, and other settings. The linter automatically searches for this file in the current and parent directories.

```yaml
# Example .protolint.yaml content
# rules:
#   - "IMPORT_PACKAGE_RELATIONSHIP"
# reporter: "junit"
```

--------------------------------

### Integrating with Claude Desktop

Source: https://github.com/yoheimuta/protolint/blob/master/mcp/README.md

Configuration steps to integrate protolint MCP server with Claude Desktop.

```APIDOC
## Integrating with Claude Desktop

### Description
Instructions to configure Claude Desktop to use protolint as an MCP server.

### Steps
1. **Edit Configuration File**: Locate and edit the `claude_desktop_config.json` file.
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. **Add MCP Server Configuration**: Add the following JSON object to the `mcpServers` section:
   ```json
   "protolint": {
     "command": "/path/to/protolint",
     "args": ["--mcp"],
     "type": "stdio"
   }
   ```
   Replace `/path/to/protolint` with the absolute path to your protolint executable.

3. **Restart Claude Desktop**: After saving the configuration file, restart Claude Desktop for the changes to take effect.
```

--------------------------------

### Configure Claude Desktop for protolint

Source: https://github.com/yoheimuta/protolint/blob/master/mcp/README.md

Add this configuration to the Claude Desktop settings file to enable the protolint MCP server.

```json
{
  "mcpServers": {
    "protolint": {
      "command": "/path/to/protolint",
      "args": ["--mcp"],
      "type": "stdio"
    }
  }
}
```

--------------------------------

### Run Protolint with CI Reporters

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Use the --add-reporter flag to generate output for specific CI/CD environments and static analysis tools.

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

--------------------------------

### Set Environment Variables for Custom Mirrors

Source: https://context7.com/yoheimuta/protolint/llms.txt

Configure environment variables to point to a custom binary download source.

```bash
# Custom mirror configuration
export PROTOLINT_MIRROR_HOST="https://internal-mirror.example.com"
export PROTOLINT_MIRROR_REMOTE_PATH="tools/protolint/releases"
export PROTOLINT_MIRROR_USERNAME="user"
export PROTOLINT_MIRROR_PASSWORD="pass"
export PROTOLINT_PROXY="http://proxy.example.com:8080"

npm install protolint
```

--------------------------------

### Create New Release with Protolint

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Automates the creation and pushing of new release tags for protolint. Requires a version number and an optional commit message.

```bash
bash release.sh <version> [message]
```

--------------------------------

### Run Protolint Programmatically with Go

Source: https://context7.com/yoheimuta/protolint/llms.txt

Utilize the protolint Go library to lint Protocol Buffer files from within your Go applications, configuring arguments and handling results.

```go
package main

import (
    "bytes"
    "fmt"
    "os"

    "github.com/yoheimuta/protolint/lib"
)

func main() {
    // Configure lint arguments (same as CLI)
    args := []string{
        "-config_path", "path/to/protolint.yaml",
        "-reporter", "json",
        "proto/",
    }

    var stdout bytes.Buffer
    var stderr bytes.Buffer

    // Run linting
    err := lib.Lint(args, &stdout, &stderr)

    // Handle results
    switch err {
    case nil:
        fmt.Println("Linting passed with no errors")
    case lib.ErrLintFailure:
        fmt.Println("Lint errors found:")
        fmt.Println(stderr.String())
        os.Exit(1)
    case lib.ErrInternalFailure:
        fmt.Println("Internal error occurred:")
        fmt.Println(stderr.String())
        os.Exit(2)
    }
}
```

--------------------------------

### Run Protolint with Docker

Source: https://context7.com/yoheimuta/protolint/llms.txt

Commands for executing linting tasks inside a Docker container.

```bash
# Lint files in current directory
docker run --volume "$(pwd):/workspace" --workdir /workspace \
    yoheimuta/protolint lint proto/

# With auto-fix
docker run --volume "$(pwd):/workspace" --workdir /workspace \
    yoheimuta/protolint lint -fix proto/

# With custom config
docker run --volume "$(pwd):/workspace" --workdir /workspace \
    yoheimuta/protolint lint -config_path=.protolint.yaml proto/

# Pin to specific version
docker run --volume "$(pwd):/workspace" --workdir /workspace \
    yoheimuta/protolint:v0.56.3 lint proto/
```

--------------------------------

### Use Multiple Reporters and Output to File

Source: https://context7.com/yoheimuta/protolint/llms.txt

Combine multiple '-reporter' flags and specify an output file for complex CI/CD integrations.

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

--------------------------------

### Lint Specific Protocol Buffer Files

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use 'protolint lint' followed by the file names to lint specific .proto files.

```bash
protolint lint example.proto example2.proto
```

--------------------------------

### Configure Pre-commit Hooks

Source: https://context7.com/yoheimuta/protolint/llms.txt

Configuration for integrating Protolint into pre-commit workflows using Go or Docker.

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/yoheimuta/protolint
    rev: v0.56.3
    hooks:
      - id: protolint
```

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/yoheimuta/protolint
    rev: v0.56.3
    hooks:
      - id: protolint-docker
        # Pin specific version via entry
        entry: yoheimuta/protolint:v0.56.3 lint
```

--------------------------------

### MCP Server - Tool: lint-files

Source: https://github.com/yoheimuta/protolint/blob/master/mcp/README.md

Documentation for the `lint-files` tool provided by the protolint MCP server.

```APIDOC
## MCP Server - Tool: lint-files

### Description
Lints Protocol Buffer files using protolint.

### Method
`tools/call` (via JSON-RPC 2.0)

### Parameters
#### Arguments
- **files** (array of strings) - Required - An array of file paths to lint.
- **config_path** (string) - Optional - Path to protolint config file.
- **fix** (boolean) - Optional - If true, attempts to fix lint errors.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": "request-1234",
  "params": {
    "name": "lint-files",
    "arguments": {
      "files": ["/path/to/file1.proto", "/path/to/file2.proto"],
      "config_path": "/path/to/config.yaml",
      "fix": true
    }
  }
}
```

### Response
#### Success Response (200)
- **content** (array of objects) - Contains the linting results.
  - **type** (string) - Type of content, e.g., "text".
  - **text** (string) - JSON string containing linting results (exit_code, results).
- **isError** (boolean) - False if the operation was successful.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "request-1234",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"exit_code\":0,\"results\":[{\"file_path\":\"/path/to/file1.proto\",\"failures\":[{\"rule_id\":\"ENUM_NAMES_UPPER_CAMEL_CASE\",\"message\":\"Enum name must be UpperCamelCase\",\"line\":5,\"column\":6,\"severity\":\"error\"}]}]}"
      }
    ],
    "isError": false
  }
}
```

### Exit Codes
- `0`: No lint errors found.
- `1`: Lint errors found.
- `2`: Internal error occurred.
```

--------------------------------

### Call protolint from Go code

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Use the lib.Lint function to execute linting programmatically, capturing output via buffers.

```go
import (
    "bytes"

    "github.com/yoheimuta/protolint/lib"
)

func main() {
    args := []string{"-config_path", "path/to/your_protolint.yaml", "."}
    var stdout bytes.Buffer
    var stderr bytes.Buffer

    err := lib.Lint(args, &stdout, &stderr)
    if err != nil {
        // Handle error
    }

    // Process output in stdout and stderr
}
```

--------------------------------

### Integrate with .NET Grpc.Tools

Source: https://github.com/yoheimuta/protolint/blob/master/cmd/protoc-gen-protolint/README.md

Configure the Protobuf item group in a .NET project file to include protolint arguments.

```xml
<ItemGroup>
  <Protobuf Include="protos\**\*.proto" AdditionalProtocArguments="--protolint_out=.;--protolint_opt=proto_root=protos" ProtoRoot="protos" />
</ItemGroup>
```

--------------------------------

### Specify proto_root for path resolution

Source: https://github.com/yoheimuta/protolint/blob/master/cmd/protoc-gen-protolint/README.md

Use the proto_root option to help the plugin locate proto files when using --proto_path.

```bash
❯ ls protos
helloworld.proto

❯ protoc \
    --proto_path=protos
    --protolint_out=. \
    --protolint_opt=proto_root=protos \
    helloworld.proto
```

--------------------------------

### Specify Custom Configuration File

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use '-config_path' to point to a custom protolint configuration file (e.g., YAML) for tailored linting rules.

```bash
protolint lint -config_path=path/to/your_protolint.yaml .
```

--------------------------------

### .NET Build Integration for Protolint

Source: https://context7.com/yoheimuta/protolint/llms.txt

An XML snippet for integrating protolint into .NET projects using the Grpc.Tools package, specifying additional protoc arguments for linting.

```xml
<ItemGroup>
  <Protobuf
    Include="protos\**\*.proto"
    AdditionalProtocArguments="--protolint_out=.;--protolint_opt=proto_root=protos"
    ProtoRoot="protos" />
</ItemGroup>
```

--------------------------------

### Protolint Configuration

Source: https://context7.com/yoheimuta/protolint/llms.txt

Configuration options for Protolint, including ignoring rules, excluding files and directories, and configuring specific rules.

```APIDOC
## Protolint Configuration

### Lint Directives

- **ignores**: Ignore specific rules for specific files.
  - **id**: The ID of the rule to ignore.
  - **files**: A list of file paths to apply the ignore rule to.
- **files.exclude**: A list of file paths to exclude from linting.
- **directories.exclude**: A list of directory paths to exclude from linting.

### Rule Configuration

- **rules.all_default**: Enable all default rules.
- **rules.no_default**: Disable all default rules.
- **rules.add**: Add specific rules to the linter.
- **rules.remove**: Remove specific rules from the default set.

### Rule-Specific Options

- **rules_option.max_line_length**: Configure maximum line length.
  - **max_chars**: Maximum number of characters per line.
  - **tab_chars**: Number of spaces equivalent to a tab.
- **rules_option.indent**: Configure indentation style.
  - **style**: Indentation style (e.g., 2, 4, tab).
  - **not_insert_newline**: Whether to not insert a newline.
- **rules_option.quote_consistent**: Configure quote style.
  - **quote**: Quote style (e.g., double, single).
- **rules_option.enum_field_names_zero_value_end_with**: Configure suffix for zero value enum fields.
  - **suffix**: The suffix to append.
- **rules_option.service_names_end_with**: Configure service name suffix requirement.
  - **text**: The required suffix text.
- **rules_option.field_names_exclude_prepositions**: Exclude prepositions from field names.
  - **prepositions**: A list of prepositions to exclude.
  - **excludes**: Specific field names to exclude from this rule.
- **rules_option.repeated_field_names_pluralized**: Configure pluralization rules for repeated fields.
  - **uncountable_rules**: Rules for uncountable words.
  - **irregular_rules**: Irregular pluralization rules.
- **rules_option.messages_have_comment**: Enforce comments for messages.
  - **should_follow_golang_style**: Whether to follow Go style comments.
- **rules_option.services_have_comment**: Enforce comments for services.
  - **should_follow_golang_style**: Whether to follow Go style comments.
- **rules_option.rpcs_have_comment**: Enforce comments for RPCs.
  - **should_follow_golang_style**: Whether to follow Go style comments.
- **rules_option.syntax_consistent**: Enforce consistent syntax version.
  - **version**: The required syntax version (e.g., proto3).
- **rules_option.file_names_lower_snake_case**: Configure file name casing rules.
  - **excludes**: File names to exclude from this rule.
```

--------------------------------

### Specify Configuration Directory

Source: https://context7.com/yoheimuta/protolint/llms.txt

The '-config_dir_path' flag allows protolint to search for configuration files within a specified directory.

```bash
protolint lint -config_dir_path=path/to .
```

--------------------------------

### Go Library API - Lint Function

Source: https://context7.com/yoheimuta/protolint/llms.txt

Programmatically lint Protocol Buffer files using the `lib.Lint` function from the Protolint Go library.

```APIDOC
## Go Library API

### lib.Lint Function

Use protolint programmatically from Go code to lint Protocol Buffer files.

```go
package main

import (
    "bytes"
    "fmt"
    "os"

    "github.com/yoheimuta/protolint/lib"
)

func main() {
    // Configure lint arguments (same as CLI)
    args := []string{
        "-config_path", "path/to/protolint.yaml",
        "-reporter", "json",
        "proto/",
    }

    var stdout bytes.Buffer
    var stderr bytes.Buffer

    // Run linting
    err := lib.Lint(args, &stdout, &stderr)

    // Handle results
    switch err {
    case nil:
        fmt.Println("Linting passed with no errors")
    case lib.ErrLintFailure:
        fmt.Println("Lint errors found:")
        fmt.Println(stderr.String())
        os.Exit(1)
    case lib.ErrInternalFailure:
        fmt.Println("Internal error occurred:")
        fmt.Println(stderr.String())
        os.Exit(2)
    }
}
```
```

--------------------------------

### Protolint Command-Line Flags

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Illustrates common Protolint command-line flags for controlling behavior, such as specifying a reporter or enabling auto-disable functionality.

```bash
# Example usage with flags
protolint -reporter junit
protolint -auto_disable next
protolint -fix
```

--------------------------------

### Output Lint Results to a File

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use '-output_file' to redirect the linting results to a specified file instead of standard output.

```bash
protolint lint -output_file=path/to/out.txt .
```

--------------------------------

### Claude Desktop MCP Server Configuration

Source: https://context7.com/yoheimuta/protolint/llms.txt

A JSON configuration for Claude Desktop to connect to a protolint MCP server, specifying the command, arguments, and type.

```json
{
  "mcpServers": {
    "protolint": {
      "command": "/usr/local/bin/protolint",
      "args": ["--mcp"],
      "type": "stdio"
    }
  }
}

Save to:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```

--------------------------------

### Configure Protolint as a Pre-commit Hook

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Add these configurations to your .pre-commit-config.yaml to run Protolint during the pre-commit process.

```yaml
repos:
  - repo: https://github.com/yoheimuta/protolint
    rev: v0.56.3 # Select a release here
    hooks:
      - id: protolint
```

```yaml
repos:
  - repo: https://github.com/yoheimuta/protolint
    hooks:
      - id: protolint-docker # Uses yoheimuta/protolint:latest by default
```

```yaml
repos:
  - repo: https://github.com/yoheimuta/protolint
    hooks:
      - id: protolint-docker
        entry: yoheimuta/protolint:v0.55.6 lint # Pin to specific version
```

--------------------------------

### GitLab CI/CD Environment Output

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use '-reporter ci-glab' to format output for GitLab CI/CD, providing annotations within merge requests and pipeline logs.

```bash
protolint lint -reporter ci-glab .
```

--------------------------------

### Implement a Custom Lint Runner in Go

Source: https://context7.com/yoheimuta/protolint/llms.txt

Create and use a custom lint runner by implementing the lib.LintRunner interface for testing or specialized linting logic.

```go
package main

import (
    "bytes"
    "io"

    "github.com/yoheimuta/protolint/lib"
)

// MockLintRunner implements lib.LintRunner for testing
type MockLintRunner struct{}

func (r *MockLintRunner) Run(args []string, stdout, stderr io.Writer) error {
    // Custom implementation
    return nil
}

func main() {
    // Save original runner
    originalRunner := lib.GetLintRunner()
    defer lib.SetLintRunner(originalRunner)

    // Set custom runner
    lib.SetLintRunner(&MockLintRunner{})

    // Now lib.Lint uses the custom runner
    var stdout, stderr bytes.Buffer
    lib.Lint([]string{"test.proto"}, &stdout, &stderr)
}
```

--------------------------------

### Configure Rule Defaults and Additions

Source: https://context7.com/yoheimuta/protolint/llms.txt

Manage default rules by enabling all, disabling defaults and adding specific rules, or removing specific rules from the defaults.

```yaml
  # Rule configuration
  rules:
    # Enable all default rules (recommended)
    all_default: true

    # Or disable defaults and add specific rules
    # no_default: true
    # add:
    #   - FIELD_NAMES_LOWER_SNAKE_CASE
    #   - MESSAGE_NAMES_UPPER_CAMEL_CASE

    # Remove specific rules from defaults
    remove:
      - RPC_NAMES_UPPER_CAMEL_CASE
```

--------------------------------

### Configure Rule-Specific Options

Source: https://context7.com/yoheimuta/protolint/llms.txt

Set specific options for various rules, such as line length, indentation, quote style, and naming conventions.

```yaml
  # Rule-specific options
  rules_option:
    # Maximum line length
    max_line_length:
      max_chars: 120
      tab_chars: 2

    # Indentation style (2 spaces, 4 spaces, or tab)
    indent:
      style: 2
      not_insert_newline: false

    # Quote style (double or single)
    quote_consistent:
      quote: double

    # Zero value enum suffix
    enum_field_names_zero_value_end_with:
      suffix: UNSPECIFIED

    # Service name suffix requirement
    service_names_end_with:
      text: Service

    # Exclude prepositions from field names
    field_names_exclude_prepositions:
      prepositions:
        - for
        - at
        - of
      excludes:
        - end_of_support

    # Pluralization rules for repeated fields
    repeated_field_names_pluralized:
      uncountable_rules:
        - paper
        - metadata
      irregular_rules:
        Irregular: Regular

    # Comment requirements with Go style
    messages_have_comment:
      should_follow_golang_style: true

    services_have_comment:
      should_follow_golang_style: true

    rpcs_have_comment:
      should_follow_golang_style: true

    # Syntax version enforcement
    syntax_consistent:
      version: proto3

    # File name exclusions
    file_names_lower_snake_case:
      excludes:
        - legacy/OldFile.proto
```

--------------------------------

### Order Protocol Buffer Elements

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Ensures Protocol Buffer elements (syntax, package, imports, options, messages) are in a specific, consistent order. This rule promotes readability and maintainability.

```diff
- 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 { }
```

--------------------------------

### Sort Imports

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Ensures imports are sorted alphabetically and public imports are grouped correctly. Use this to maintain consistent import order.

```diff
- 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";
```

--------------------------------

### Generate SARIF Report

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use '-reporter sarif' to output lint results in SARIF format, compatible with tools like GitHub CodeQL.

```bash
protolint lint -reporter sarif .
```

--------------------------------

### Register Custom Rules in Go Plugin

Source: https://context7.com/yoheimuta/protolint/llms.txt

This Go code demonstrates how to register custom lint rules, including static rules and configurable rules that use runtime flags.

```go
package main

import (
    "flag"

    "github.com/yoheimuta/protolint/linter/rule"
    "github.com/yoheimuta/protolint/plugin"
)

var (
    goStyle = flag.Bool("go_style", true, "enforce golang style comments")
)

func main() {
    flag.Parse()

    plugin.RegisterCustomRules(
        // Register static rules
        NewMyCustomRule(),

        // Register rules that need runtime flags using RuleGen
        plugin.RuleGen(func(verbose bool, fixMode bool) rule.Rule {
            return NewConfigurableRule(verbose, fixMode, *goStyle)
        }),
    )
}
```

--------------------------------

### Configure Ignored Rules and Files

Source: https://context7.com/yoheimuta/protolint/llms.txt

Specify rules to ignore for particular files or exclude entire files and directories from linting.

```yaml
lint:
  # Ignore specific rules for specific files
  ignores:
    - id: MESSAGE_NAMES_UPPER_CAMEL_CASE
      files:
        - path/to/legacy.proto
    - id: ENUM_NAMES_UPPER_CAMEL_CASE
      files:
        - path/to/external_api.proto

  # Files to exclude from linting
  files:
    exclude:
      - path/to/generated.proto
      - vendor/**/*.proto

  # Directories to exclude
  directories:
    exclude:
      - third_party
      - vendor
```

--------------------------------

### GitHub Actions CI Environment Output

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use '-reporter ci-gh' to format output for GitHub Actions, which automatically creates annotations in the workflow logs.

```bash
protolint lint -reporter ci-gh .
```

--------------------------------

### Custom CI Reporter Template

Source: https://context7.com/yoheimuta/protolint/llms.txt

Set the PROTOLINT_CIREPORTER_TEMPLATE_STRING environment variable to define a custom format for CI environment reporters.

```bash
export PROTOLINT_CIREPORTER_TEMPLATE_STRING='{{.Severity}}: {{.Rule}} at {{.File}}:{{.Line}}:{{.Column}} - {{.Message}}'
protolint lint -reporter ci-env .
```

--------------------------------

### Lint with Verbose Output

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use the '-v' flag with 'protolint lint' for verbose output, which is helpful for diagnosing parsing errors.

```bash
protolint lint -v .
```

--------------------------------

### Generate Unix Format Report

Source: https://context7.com/yoheimuta/protolint/llms.txt

The '-reporter unix' flag outputs lint results in a standard Unix-like format.

```bash
protolint lint -reporter unix .
```

--------------------------------

### Go Library API - Custom Lint Runner

Source: https://context7.com/yoheimuta/protolint/llms.txt

Override the default lint runner in the Protolint Go library for custom testing or implementations.

```APIDOC
### Custom Lint Runner

Override the default lint runner for testing or custom implementations.

```go
package main

import (
    "bytes"
    "io"

    "github.com/yoheimuta/protolint/lib"
)

// MockLintRunner implements lib.LintRunner for testing
type MockLintRunner struct{}

func (r *MockLintRunner) Run(args []string, stdout, stderr io.Writer) error {
    // Custom implementation
    return nil
}

func main() {
    // Save original runner
    originalRunner := lib.GetLintRunner()
    defer lib.SetLintRunner(originalRunner)

    // Set custom runner
    lib.SetLintRunner(&MockLintRunner{})

    // Now lib.Lint uses the custom runner
    var stdout, stderr bytes.Buffer
    lib.Lint([]string{"test.proto"}, &stdout, &stderr)
}
```
```

--------------------------------

### Generate JUnit XML Report

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use '-reporter junit' to output lint results in JUnit XML format, suitable for integration with CI/CD systems.

```bash
protolint lint -reporter junit .
```

--------------------------------

### Disable Rules with Comments

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Demonstrates how to disable specific linting rules within a Protocol Buffer file using `protolint:disable` and `protolint:enable` comments. Rules can be disabled for the entire file or specific lines.

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

```proto
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
}
```

--------------------------------

### Call lint-files via MCP

Source: https://context7.com/yoheimuta/protolint/llms.txt

JSON-RPC request and response format for the lint-files MCP tool.

```json
// Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": "request-1234",
  "params": {
    "name": "lint-files",
    "arguments": {
      "files": ["/path/to/file1.proto", "/path/to/file2.proto"],
      "config_path": "/path/to/config.yaml",
      "fix": true
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": "request-1234",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"exit_code\":0,\"results\":[{\"file_path\":\"/path/to/file1.proto\",\"failures\":[{\"rule_id\":\"ENUM_NAMES_UPPER_CAMEL_CASE\",\"message\":\"Enum name must be UpperCamelCase\",\"line\":5,\"column\":6,\"severity\":\"error\"}]}]}"
      }
    ],
    "isError": false
  }
}
```

--------------------------------

### Generate SonarQube Report

Source: https://context7.com/yoheimuta/protolint/llms.txt

The '-reporter sonar' flag generates lint results in the generic issue format for SonarQube.

```bash
protolint lint -reporter sonar .
```

--------------------------------

### Azure DevOps CI Environment Output

Source: https://context7.com/yoheimuta/protolint/llms.txt

The '-reporter ci-az' flag formats output for Azure DevOps pipelines, enabling native annotations.

```bash
protolint lint -reporter ci-az .
```

--------------------------------

### Add Disable Comments Without Fixing

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use '-auto_disable=next' without '-fix' to only insert disable comments for unfixable issues, without modifying the code.

```bash
protolint lint -auto_disable=next .
```

--------------------------------

### Generate TypeScript Compiler Compatible Output

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use '-reporter tsc' to format lint results in a way that is compatible with the TypeScript compiler's output.

```bash
protolint lint -reporter tsc .
```

--------------------------------

### Package Name Lower Case

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Enforces that package names are in lower case. This rule helps in maintaining a consistent naming convention for packages.

```diff
- package myPackage
+ package my.package
```

--------------------------------

### Generate JSON Report

Source: https://context7.com/yoheimuta/protolint/llms.txt

The '-reporter json' flag generates lint results in JSON format, which is easily parsable by machines.

```bash
protolint lint -reporter json .
```

--------------------------------

### Implement Custom Lint Rule in Go

Source: https://context7.com/yoheimuta/protolint/llms.txt

This Go code implements a custom lint rule 'EnumNamesLowerSnakeCaseRule' that verifies enum names adhere to the lower_snake_case format. It includes methods for rule identification, purpose, severity, and applying the rule using a visitor pattern.

```go
package customrules

import (
    "github.com/yoheimuta/go-protoparser/v4/parser"

    "github.com/yoheimuta/protolint/linter/report"
    "github.com/yoheimuta/protolint/linter/rule"
    "github.com/yoheimuta/protolint/linter/strs"
    "github.com/yoheimuta/protolint/linter/visitor"
)

// EnumNamesLowerSnakeCaseRule verifies enum names are lower_snake_case.
type EnumNamesLowerSnakeCaseRule struct{}

// NewEnumNamesLowerSnakeCaseRule creates the rule.
func NewEnumNamesLowerSnakeCaseRule() EnumNamesLowerSnakeCaseRule {
    return EnumNamesLowerSnakeCaseRule{}
}

// ID returns the rule ID (must be UPPER_SNAKE_CASE).
func (r EnumNamesLowerSnakeCaseRule) ID() string {
    return "ENUM_NAMES_LOWER_SNAKE_CASE"
}

// Purpose returns human-readable description.
func (r EnumNamesLowerSnakeCaseRule) Purpose() string {
    return "Verifies that all enum names are lower_snake_case."
}

// IsOfficial indicates if rule is from official style guide.
func (r EnumNamesLowerSnakeCaseRule) IsOfficial() bool {
    return false
}

// Severity returns the rule severity (note, warning, error).
func (r EnumNamesLowerSnakeCaseRule) Severity() rule.Severity {
    return rule.SeverityWarning
}

// Apply runs the rule against a parsed proto file.
func (r EnumNamesLowerSnakeCaseRule) Apply(proto *parser.Proto) ([]report.Failure, error) {
    v := &enumNamesLowerSnakeCaseVisitor{
        BaseAddVisitor: visitor.NewBaseAddVisitor(r.ID(), string(r.Severity())),
    }
    return visitor.RunVisitor(v, proto, r.ID())
}

type enumNamesLowerSnakeCaseVisitor struct {
    *visitor.BaseAddVisitor
}

// VisitEnum is called for each enum in the proto file.
func (v *enumNamesLowerSnakeCaseVisitor) VisitEnum(e *parser.Enum) bool {
    if !strs.IsLowerSnakeCase(e.EnumName) {
        v.AddFailuref(e.Meta.Pos, "Enum name %q must be lower_snake_case", e.EnumName)
    }
    return false // don't visit children
}
```

--------------------------------

### Consistent Quoting

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Ensures consistent use of double quotes for string values in options. This rule helps maintain a uniform style across the configuration.

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

--------------------------------

### Auto-Fix and Add Disable Comments

Source: https://context7.com/yoheimuta/protolint/llms.txt

Combine '-fix' with '-auto_disable=next' to fix what's possible and add inline disable comments for unfixable issues, preserving API compatibility.

```bash
protolint lint -fix -auto_disable=next .
```

--------------------------------

### Service Names Upper Camel Case

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Enforces that service names follow the UpperCamelCase convention. This rule standardizes the naming of services.

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

--------------------------------

### Lint Without Error on Unmatched Pattern

Source: https://context7.com/yoheimuta/protolint/llms.txt

The '-no-error-on-unmatched-pattern' flag ensures the command exits successfully even if no files match the specified pattern.

```bash
protolint lint -no-error-on-unmatched-pattern .
```

--------------------------------

### Indentation Consistency

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Maintains consistent indentation within Protocol Buffer definitions, including enums and messages. This rule improves code readability.

```diff
 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"];
- }
+} 
```

```diff
-   message TestMessage { string test_field = 1; }
+ message TestMessage {
+  string test_field = 1;
+}
```

--------------------------------

### Disable Rules Inline in Proto Files

Source: https://context7.com/yoheimuta/protolint/llms.txt

Use comments within Protocol Buffer files to disable specific rules for a block of code or the next line.

```protobuf
syntax = "proto3";

package example;

// Disable rules until re-enabled
// protolint:disable ENUM_FIELD_NAMES_UPPER_SNAKE_CASE MESSAGE_NAMES_UPPER_CAMEL_CASE

enum legacyEnum {
  legacy_value = 0;
}

message legacy_message {
  string field = 1;
}

// Re-enable rules
// protolint:enable ENUM_FIELD_NAMES_UPPER_SNAKE_CASE MESSAGE_NAMES_UPPER_CAMEL_CASE

// Disable for next line only
// protolint:disable:next ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
enum AnotherEnum {
  another_value = 0;  // This violation is ignored
  PROPER_VALUE = 1;   // Back to normal checking
}

// Disable for current line
message ProperMessage {
  string improper_Name = 1;  // protolint:disable:this FIELD_NAMES_LOWER_SNAKE_CASE
  string proper_name = 2;
}
```

--------------------------------

### Inline Rule Disabling

Source: https://context7.com/yoheimuta/protolint/llms.txt

How to disable specific linting rules directly within Protocol Buffer files using comments.

```APIDOC
## Inline Rule Disabling

### Disable Rules in Proto Files

Control linting behavior directly in Protocol Buffer files using comments.

```protobuf
syntax = "proto3";

package example;

// Disable rules until re-enabled
// protolint:disable ENUM_FIELD_NAMES_UPPER_SNAKE_CASE MESSAGE_NAMES_UPPER_CAMEL_CASE

enum legacyEnum {
  legacy_value = 0;
}

message legacy_message {
  string field = 1;
}

// Re-enable rules
// protolint:enable ENUM_FIELD_NAMES_UPPER_SNAKE_CASE MESSAGE_NAMES_UPPER_CAMEL_CASE

// Disable for next line only
// protolint:disable:next ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
enum AnotherEnum {
  another_value = 0;  // This violation is ignored
  PROPER_VALUE = 1;   // Back to normal checking
}

// Disable for current line
message ProperMessage {
  string improper_Name = 1;  // protolint:disable:this FIELD_NAMES_LOWER_SNAKE_CASE
  string proper_name = 2;
}
```
```

--------------------------------

### RPC Names Upper Camel Case

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Ensures RPC method names in services follow the UpperCamelCase convention. This rule standardizes the naming of RPC endpoints.

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

--------------------------------

### Repeated Field Names Pluralized

Source: https://github.com/yoheimuta/protolint/blob/master/README.md

Ensures that repeated field names are pluralized. This convention improves clarity when dealing with collections of items.

```diff
-  repeated string song_name = 1;
+  repeated string song_names = 1;
```
Tokens:
Raw