buf-check-reserved-keywords

This repository contains a buf check plugin that checks for use of language reserved keywords in protobuf files.

It is published to the BSR at svanburenorg/reserved-keywords.

Usage

You can find usage instructions on the BSR at svanburenorg/reserved-keywords, but to summarize:

1. Add the following to your buf.yaml's plugins: stanza:

- plugin: buf.build/svanburenorg/reserved-keywords:main

2. Run the following command to download the plugin to your local environment:

$ buf plugin update

3. If you have any lint.use rules specified (you probably have DEFAULT already added from the default buf config init), you'll need to explicitly add the lint rule to your lint.use stanza:

lint:
  use:
    - DEFAULT
+   - PLUGIN_PACKAGE_NO_LANGUAGE_RESERVED_KEYWORDS
+   - PLUGIN_FIELD_NO_LANGUAGE_RESERVED_KEYWORDS

Options

buf-check-reserved-keywords currently supports a single option, enabled_languages. If not specified, the plugin checks for keywords for all supported languages. If specified, only the specified languages are checked.

For example, the following enables just checking for keywords for go and python.

- plugin: buf.build/svanburenorg/reserved-keywords:main
  options:
    enabled_languages:
      - go
      - python

Ignoring

Where a keyword is known not to cause problems, use buf's lint ignores. Ignore a single field or package with a comment on the line above it:

// buf:lint:ignore PLUGIN_PACKAGE_NO_LANGUAGE_RESERVED_KEYWORDS
package map.v1;

message Robot {
  // buf:lint:ignore PLUGIN_FIELD_NO_LANGUAGE_RESERVED_KEYWORDS
  string type = 1;
}

Or ignore a rule for whole directories or files with ignore_only in buf.yaml:

lint:
  ignore_only:
    PLUGIN_FIELD_NO_LANGUAGE_RESERVED_KEYWORDS:
      - proto/legacy

Why?

While it's considered best practice to avoid using language reserved keywords for protobuf types, the default buf linter does not contain any checks to prevent their usage, as this would require buf to know about the reserved keywords of various languages.

This plugin serves as a place to add these reserved keywords, and prevent their usage in protobuf files.

Supported Languages

• C
• C++
• C#
• Dart
• Go
• Java
• JavaScript
• Kotlin
• Objective-C
• PHP
• Python
• Ruby
• Rust
• Scala
• Swift
• TypeScript

Go keywords are checked in package names only: protoc-gen-go exports every field under a PascalCase name (map becomes Map), so a field named after a Go keyword does not collide.