Document buffrs lint

docs/src/SUMMARY.md

@@ -26,7 +26,7 @@
     * [Cargo](integrations/cargo.md)
     * [Poetry]()
 
-* [Buffrs Reference]()
+* [Buffrs Reference](reference/index.md)
     * [Specifying Dependencies]()
         * [Overriding Dependencies]()
     * [The Manifest Format]()
@@ -35,6 +35,7 @@
     * [Build Configuration]()
     * [Publishing on buff.rs]()
     * [Package Name Specifications]()
+    * [Protocol Buffer Rules](reference/protocol-buffer-rules.md)
     * [Dependency Resolution]()
     * [SemVer Compatibility]()
 

docs/src/commands/buffrs-lint.md

@@ -0,0 +1,45 @@
+## buffrs lint
+
+Lints your protocol buffers for the ([Buffrs Protocol Buffer
+Rules](../reference/protocol-buffer-rules.md)
+
+### Synopsis
+
+`buffrs lint`
+
+### Description
+
+This command lints your local package (defined in `proto/*.proto`) for a set of
+rules defined in the ([Buffrs Protocol Buffer
+Rules](../reference/protocol-buffer-rules.md)). They contain a set of rules
+ranging from style to package layout (like filenaming, package declaration
+etc.). This enables a common flavor to Buffrs packages which affect users.
+
+One good example why this is required is the enforcement of euqality between
+the package declaration in the protocol buffers files (`*.proto`) and the
+Buffrs Package ID. This enables to expect that a Buffrs Package `a` declares
+the protocol buffer package `a.*` and prevents type colisions / ambiguity.
+
+### Example
+
+Given a Buffrs Package `abc` that contains a protocol buffer file with the
+following file (`proto/xyz.proto`):
+
+```proto
+syntax = "proto3";
+
+package xyz;
+```
+
+Executing `buffrs lint` would return a rule violation:
+
+```toml
+PackageName (https://helsing-ai.github.io/buffrs/rules/PackageName)
+
+  × Make sure that the protobuf package name matches the buffer package name.
+  ╰─▶   × package name is xyz but should have abc prefix
+
+   ╭─[xyz.proto:1:1]
+   ╰────
+  help: Make sure the file name matches the package. For example, a package with the name `package.subpackage` should be stored in `proto/package/subpackage.proto`.
+```

docs/src/commands/index.md

@@ -1,4 +1,4 @@
-# Buffrs commands
+# Buffrs Commands
 
 This section covers detailed documentation on operating the Buffrs CLI. Some of
 the content may also apply to the library, particularly the `command` module.
@@ -28,4 +28,4 @@ generally be more up-to-date.
 * [Publishing Commands](publishing-commands.md)
     * [buffrs login](buffrs-login.md)
     * [buffrs logout](buffrs-logout.md)
-    * [buffrs publish](buffrs-publish.md)
+    * [buffrs publish](buffrs-publish.md)

docs/src/reference/index.md

@@ -0,0 +1,7 @@
+# Buffrs Reference
+
+This section covers detailed documentation on the Buffrs Ecosystem / Framework.
+
+## Index
+
+* [Protocol Buffer Rules](protocol-buffer-rules.md)

docs/src/reference/protocol-buffer-rules.md

@@ -0,0 +1,38 @@
+## Protocol Buffer Rules
+
+This specification defines rules enforced by Buffrs to prevent package
+colisions, and provide uniformity and transparency for package consumers.
+
+Rules with the `00XX` code define the package and filesystem layout, where as
+rules with a `01XX` code enforce certain protocol buffer definition rules.
+
+### `0000` – Package Name Prefix / Symmetry
+
+Enforces that the Buffrs Package ID is used as the prefix for all protocol
+buffer package declarations.
+
+So given a Buffrs Package with the ID `physics` this enforces that the package
+only contains protocol buffer package declarations matching
+`physics|physics.*`;
+
+A violation would cause type colisions and ambiguity when trying to resolve a
+type.
+
+### `0010` – Sub-Package Declaration
+
+Enforces that subpackages are declared through a sensible folder
+structure. Given a Buffrs Package with the ID `physics` the protocol buffer
+file that declares `package physics.units;` has to be called
+`proto/units.proto`.
+
+Nested subpackages are represented / grouped through folders. So if one wants
+to declare `package physics.units.temperature;` the respective file must be
+located at `proto/units/temperature.proto`.
+
+### `0020` – Root Package Declaration
+
+Enforces that only one file at a time declares the _root_ package.
+
+Namely: If a Buffrs Package with the ID `physics` is defined, the
+`proto/physics.proto` must declare the the same package in the protocol buffer
+syntax through `package physics;`.