profmt 0.1.0

A fast, deterministic, configurable Protocol Buffers formatter built on tree-sitter
Documentation
# profmt

[![Crates.io](https://img.shields.io/crates/v/profmt.svg)](https://crates.io/crates/profmt)
[![Documentation](https://docs.rs/profmt/badge.svg)](https://docs.rs/profmt)
[![MIT licence](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A fast, deterministic Protocol Buffers formatter powered by
[tree-sitter](https://tree-sitter.github.io/) and written in Rust.

profmt turns this:

```proto
syntax = "proto2";
import "validation.proto";
import "http.proto";
package example.v1;
service Greeter { rpc Hello(HelloRequest) returns(HelloResponse) {
    option (http).route="/hello";
  };
}
message HelloRequest { optional string name=1 [(validation).required=true]; };
```

into this:

```proto
syntax = "proto2";
import "validation.proto";
import "http.proto";
package example.v1;
service Greeter {
  rpc Hello(HelloRequest) returns (HelloResponse) {
    option (http).route = "/hello";
  }
}
message HelloRequest {
  optional string name = 1 [(validation).required = true];
}
```

and, with the configuration shown [below](#configuration), into this:

```proto
syntax = "proto2";

import "http.proto";
import "validation.proto";

package example.v1;

service Greeter {
    rpc Hello(HelloRequest) returns (HelloResponse) {
        option (http).route = "/hello";
    }
}

message HelloRequest {
    optional string name = 1 [(validation).required = true];
}
```

## Quick start

Install profmt with Homebrew:

```sh
brew install AllyMarthaJ/tap/profmt
```

Or install it with Cargo:

```sh
cargo install --locked profmt
```

Then format or check a project:

```sh
profmt --write .         # Format every .proto file in place.
profmt --check .         # Check formatting without changing files.
profmt --check --diff .  # Show what would change.
```

profmt finds `.proto` files, respects `.gitignore`, and formats files in
parallel. Pass one file without `--write` or `--check` to print the result,
or use `-` to read standard input.

## Highlights

- **Fast:** directory discovery and formatting both run in parallel; a check
  never allocates the formatted output.
- **Deterministic:** parallel work still produces stable output and reporting.
- **Configurable:** project policy lives in `.profmt.toml`, not formatter
  special cases. Every layout a project could reasonably choose either way is
  an option with a `preserve` variant.
- **Strict:** invalid input, parse errors, and misspelled configuration keys
  fail visibly. Formatting never changes a token other than a string
  delimiter you asked for.
- **Complete:** proto2, proto3 and editions, including groups, extensions,
  streams, text-format option values and comments anywhere.
- **Embeddable:** the Rust library exposes the same formatter and
  allocation-free checks as the CLI.

## Configuration

The defaults are project-neutral: two-space indentation, 80 columns, and the
source's own choice wherever projects disagree.

Add `.profmt.toml` at the root of a project to change that:

```toml
indent_width = 4
line_width = 120
quote_style = "double"
header_order = "imports_first"
import_order = "sorted"
empty_rpc_body = "semicolon"
declaration_spacing = "separated"
comment_spacing = "normalized"
```

profmt searches the current directory and its parents for the nearest config
file. CLI options override the file for one run.

See the [configuration reference](docs/configuration.md) for every option and
its default value.

## Library

Use profmt as a Rust library when formatting needs to live inside another
tool:

```rust
use profmt::{FormatOptions, QuoteStyle, format_with_options};

let options = FormatOptions {
    quote_style: QuoteStyle::Double,
    ..FormatOptions::default()
};

let output = format_with_options(b"import 'a.proto';\n", &options)?;
assert_eq!(output, "import \"a.proto\";\n");
# Ok::<(), anyhow::Error>(())
```

Read the [API documentation](https://docs.rs/profmt) for the complete library
interface.

## More

- [Behavior, safety, and performance]docs/behavior.md
- [Configuration reference]docs/configuration.md
- [Contributing]CONTRIBUTING.md

## Licence

profmt is available under the [MIT licence](LICENSE).