prim-fmt

The formatting engine behind prim — an opinionated, near-zero-config formatter for a repository's connective tissue (Markdown, JSON/JSONC, YAML, TOML) plus whitespace hygiene.

This crate is the pure library: strings in, strings out, no CLI or terminal dependencies, so other tools can embed it. The prim binary is published separately as prim-cli.

Status: early. classify + format apply the whitespace-hygiene pass to the parsed formats and the orphan allowlist; structured per-format passes land in later milestones. See the specification.

Usage

use std::path::Path;

// Classify a file by name, then format its contents for that kind.
if let Some(kind) = prim_fmt::classify(Path::new("README.md")) {
    let formatted = prim_fmt::format(kind, "# Title  \n");
    assert_eq!(formatted, "# Title\n");
}

Correctness fixtures

tests/correctness/fixtures/<format>/*.txt drive the correctness harness (FR-6.1 idempotency, FR-6.2 semantic preservation, plus format-equality). Each file has -- input -- and -- expected -- sections, plus an optional -- config -- section overriding the default Style. The directory name selects the FileKind (json, jsonc, toml, yaml, markdown, hygiene).

To add a fixture: create the file with your -- input -- and an empty -- expected --, then run:

PRIM_SPEC_UPDATE=1 cargo test -p prim-fmt --test correctness spec_cases_format_as_expected

Review the generated diff before committing — this is the step where a formatter bug would show up as unexpected output.

Benchmarks

benches/format.rs times format() per file kind (JSON, TOML, YAML, Markdown) across small/medium/large synthetic inputs generated at bench time (no vendored corpus — deterministic and reproducible). Run:

just bench

This is not part of just check or CI — it's slow and its numbers are machine-dependent, so it's for local regression-hunting, not a gate. HTML reports land in target/criterion/report/index.html. There is currently no tracked performance baseline; treat a run before and after your change as the comparison, not an absolute number.

License

MIT © driftsys