profmt 0.1.0

A fast, deterministic, configurable Protocol Buffers formatter built on tree-sitter
Documentation
# Behavior, safety, and performance

## Inputs

profmt accepts standard input, files, and directories.

- Directory traversal selects `.proto` files.
- Standard ignore files such as `.gitignore` apply.
- Hidden paths are included unless an ignore rule excludes them.
- Symbolic links are rejected and never followed.
- Explicit files are accepted regardless of extension.

File discovery and formatting run in parallel. Results are reported in sorted
path order.

Use `--threads N` to select a fixed worker count. Directory discovery uses at
most four workers because additional walkers increase filesystem contention.
Single-threaded mode bypasses the Rayon pool.

## Modes and exit status

Without `--write` or `--check`, profmt requires one input and prints the
formatted source to standard output.

`--write` replaces changed files. `--check` changes no files and exits with
status 1 if any file would change. Add `--diff` to print unified diffs.

| Status | Meaning |
| ---: | --- |
| 0 | Every input succeeded, and `--check` found no changes. |
| 1 | `--check` found at least one change. |
| 2 | An input, configuration, or formatter operation failed. |

## Layout

profmt prints one statement per line. By default a declaration stays on its
line however long it is: a dangling `returns`, a lone option in brackets, or
a value separated from its `option` is worse than a long line. Each of those
breaks is available as an opt-in: `rpc_signature_layout`,
`field_options_layout` and `option_value_layout`.

A text-format message literal is data rather than a declaration, so it
breaks one entry per line when it does not fit, keeping the separators the
source used.

Comments are never re-wrapped. A comment on the same line as code stays at
the end of that line; a comment on its own line stays on its own line; a
multi-line block comment is re-indented under its opening `/*`. A `//`
comment inside a statement moves to the end of the statement's line.

## Safe writes

Before profmt replaces a file, it:

1. Rejects symbolic links and non-regular files.
2. Writes a unique temporary file in the same directory.
3. Preserves the original permissions.
4. Re-reads the source and rejects concurrent changes.
5. Renames the completed temporary file over the source.

If cleanup also fails, profmt reports both the original error and the cleanup
error.

## Failures

profmt returns an error for invalid UTF-8, parse errors, and invalid
configuration. It does not replace invalid text.

An input byte-order mark is preserved.

## Performance

A release build checked 603 `.proto` files (3.1 MB) on a 14-core Apple M4 Max
with a warm filesystem cache:

| Workers | Wall time |
| ---: | ---: |
| 1 | 0.20 s |
| 14 | 0.03 s |

The command was `profmt --check .`. The measurement includes ignore-aware
discovery, file reads, parsing, layout, and comparison. Parsing accounts for
most of the single-threaded time. Results vary with the corpus, hardware,
filesystem cache, and configured worker count.

tree-sitter parses each file once. profmt walks the tree once, constructing a
compact arena-backed document; unchanged source remains byte spans instead of
copied strings, and a check compares the rendering against the source without
allocating it.