package-directory-match (Protobuf linter rule)

package-directory-match

Since 0.9.0

This rule checks whether every Protobuf file is in the directory that corresponds to its package, for example acme/pets/v1 for the package acme.pets.v1.

Rule Details

When the directories mirror the packages, the import path of a file tells where its declarations live, and the files of a package are easy to find. Many code generators and build tools expect this layout.

The expected directory of a package is its name with the dots replaced by slashes. The package-directory-match rule compares it with the directory of the file in one of two ways:

If the file is inside one of the import paths (given with --proto-path or with the import_paths key of the configuration), the directory of the file relative to the first import path that contains it must be the expected directory. Otherwise the rule reports Package '<package>' should be in directory '<expected>' of import path '<import path>', not in '<directory>', where <directory> is . for a file directly in the import path. The import path is shown as an absolute path.
Otherwise, the directory of the file must end with the expected directory. If it does not, the rule reports Package '<package>' should be in a directory ending with '<expected>'.

Import paths in the configuration are relative to the directory of the configuration file:

version: "1.0"
commands:
  lint:
    protobuf:
      import_paths: [proto]

Files without a package, and files linted without a path, are not checked.

Configuration

This rule has no options.

Examples

Good. The file proto/acme/pets/v1/pet.proto:

syntax = "proto3";

package acme.pets.v1;

message Pet {
  string name = 1;
}

Bad. Without import paths, the file proto/pets/v1/pet.proto makes the linter report Package 'acme.pets.v1' should be in a directory ending with 'acme/pets/v1'. With the import path proto, and the project in /work, it reports Package 'acme.pets.v1' should be in directory 'acme/pets/v1' of import path '/work/proto', not in 'pets/v1'.

syntax = "proto3";

package acme.pets.v1;

message Pet {
  string name = 1;
}

When Not to Use It

You may disable this rule if your build places the files in directories that are unrelated to their packages, for example a flat directory of .proto files.

Compatibility