Protobuf Linter#

Lint .proto files for style violations, naming issues, breaking changes, and best practices.

Commands#

bash

# Lint a proto file (all rules)
python3 scripts/protobuf_linter.py lint path/to/file.proto

# Check naming conventions only
python3 scripts/protobuf_linter.py naming path/to/file.proto

# Check for breaking changes between two versions
python3 scripts/protobuf_linter.py breaking path/to/old.proto path/to/new.proto

# Validate syntax and structure
python3 scripts/protobuf_linter.py validate path/to/file.proto

# Lint a directory recursively
python3 scripts/protobuf_linter.py lint path/to/protos/ --recursive

# JSON output
python3 scripts/protobuf_linter.py lint path/to/file.proto --format json

# Summary only
python3 scripts/protobuf_linter.py lint path/to/file.proto --format summary

Rules (24)#

Structure (6)#

• Missing syntax declaration
• Missing package declaration
• Empty message/enum/service definitions
• Duplicate field numbers
• Reserved field number conflicts
• Import not found (relative path check)

Naming (8)#

• Message names must be CamelCase
• Enum names must be CamelCase
• Enum values must be UPPER_SNAKE_CASE
• Enum values must be prefixed with enum name
• Field names must be lower_snake_case
• Service names must be CamelCase
• RPC method names must be CamelCase
• Package names must be lower_snake_case with dots

Compatibility (5)#

• Changed field type (breaking)
• Removed field without reserving number (breaking)
• Changed field number (breaking)
• Renamed enum value (breaking)
• Changed RPC request/response type (breaking)

Best Practices (5)#

• Use proto3 syntax (proto2 warning)
• Avoid required fields (proto2)
• Use wrapper types for optional semantics
• Comment coverage (messages/services)
• File should match package name

Output Formats#

• text (default): Human-readable with colors and severity icons
• json: Machine-readable with file, line, rule, severity, message
• summary: Counts by severity only

Exit Codes#

• 0: No issues (or warnings only)
• 1: Errors found
• 2: Invalid input