package-options-consistent

Since 0.9.0 · In the rulesets: Recommended at error, Strict at error, All at error

This rule checks whether the files of a package set the same language-specific file options, such as go_package and java_package.

Rule details

Options like go_package, java_package and csharp_namespace tell the code generators where to put the generated code. When the files of one Protobuf package disagree on them, the code of the package is scattered over several packages or namespaces of the target language, or does not compile at all.

The package-options-consistent rule compares the options of the linted file with those of the other files of the same package. For every checked option whose value differs from that of another file, including when the option is set in one file only, it reports:

Option '<option>' differs between the files of package '<package>': <value> here, <value> in <file name>

where each value is the value in quotes, or unset. At most one issue is reported per option, for the first other file that differs. The issue is reported at the option statement, or at the package declaration when the linted file does not set the option. String values are compared after decoding their escapes; other values, such as true, as they are written.

By default the rule checks these options: csharp_namespace, go_package, java_multiple_files, java_package, objc_class_prefix, php_namespace, ruby_package and swift_prefix.

The other files of the package are those the linter knows about: the files being linted, the other .proto files in their directories, and the files these import, directly or indirectly. Files that cannot be read, for example because of syntax errors, or because they are proto2 or editions files, are ignored. Files without a package are not checked.

The rule reads the other files of the package: the other files in the directories of the linted files, and the imported files, found in the import paths and in the directories above the importing file.

If you do not generate code for some languages, restrict the list of options to those you use.

Configuration

The configuration block can be an array of option names, or an object with the options property, whose value is such an array. The list replaces the default list of options.

Configuration example. The following two examples are equivalent. They specify that only go_package and java_package must be consistent.

version: "1.0"
commands:
  lint:
    protobuf:
      rules:
        package-options-consistent: [error, [go_package, java_package]]
version: "1.0"
commands:
  lint:
    protobuf:
      rules:
        package-options-consistent:
          - error
          - options: [go_package, java_package]

Examples

Good. The directory acme/pets/v1 contains pet.proto:

syntax = "proto3";

package acme.pets.v1;

option go_package = "example.com/acme/pets/v1;petsv1";

message Pet {
  string name = 1;
}

and owner.proto:

syntax = "proto3";

package acme.pets.v1;

option go_package = "example.com/acme/pets/v1;petsv1";

message Owner {
  string name = 1;
}

Bad. The directory contains the same pet.proto as above, and this owner.proto:

syntax = "proto3";

package acme.pets.v1;

message Owner {
  string name = 1;
}

The linter reports, in pet.proto:

Option 'go_package' differs between the files of package 'acme.pets.v1': 'example.com/acme/pets/v1;petsv1' here, unset in owner.proto

and in owner.proto:

Option 'go_package' differs between the files of package 'acme.pets.v1': unset here, 'example.com/acme/pets/v1;petsv1' in pet.proto

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.protobuf has the details.

commands:
  lint:
    protobuf:
      rules:
        package-options-consistent: off

Related rules

Was this helpful?