Crate noya_cli 

Shared CLI surface for the noyafmt and noyavalidate binaries.

The same clap::Command builders the binaries use to parse their argv at runtime are also consumed by the build script (build.rs) and the cargo xtask runner — so the binaries, the man pages, and the shell completions can never drift.

Surface

• NoyafmtCli / NoyavalidateCli — the parsed-args structs produced by clap’s derive macros. main() in each binary matches against fields of these.
• noyafmt_command / noyavalidate_command — the underlying clap::Command tree. Used by clap_complete and clap_mangen to generate completions and man pages respectively.

Cargo features

This crate exposes no optional features of its own — both binaries always ship with the same dispatch surface. The transitive noyalib dependency is consumed with its default feature set (std + the always-on parser / serializer / Value / CST). To opt into optional noyalib features (schema, parallel, miette, …), pin the version directly and select features at the consuming binary’s Cargo.toml; the noyalib feature matrix is canonicalised in crates/noyalib/src/lib.rs.

MSRV

Rust 1.85.0 stable. The clap_builder 4.6 dep pulls edition-2024 helpers and floors the MSRV at 1.85; the core noyalib library still builds on 1.75. CI verifies both floors via the Per-crate MSRV workflow job. The bump policy is documented in the workspace POLICIES.md.

Panics

Public functions in this crate do not panic. The two binaries (noyafmt, noyavalidate) handle argv-parse failures via clap’s error path — surfaced as exit code 2, never as a panic.

Errors

Binary exit codes follow Unix convention: 0 on success, 1 on a YAML/schema problem, 2 on argv-parse error. Library-side errors flow through noyalib::Error (not re-exported here — call sites that want library access should depend on noyalib directly).

Concurrency

NoyafmtCli / NoyavalidateCli are Send + Sync (plain POD parsed-args structs). The clap::Command builders return owned values; cheap to clone. No interior mutability.

Platform support

Tier-1 (CI-verified each PR): aarch64-apple-darwin, x86_64-unknown-linux-gnu, x86_64-pc-windows-msvc. Both binaries write via an atomic file replacement pattern (write to a sibling temp file → sync_all → rename), so concurrent readers always see either the pre-edit or the post-edit contents — never a half-written truncation.

Performance

Each YAML file in argv flows through the underlying noyalib::cst::parse_document call (formatter) or noyalib::from_str::<Value> (validator) — both run in O(n) over input bytes. Argv-batch processing is sequential by design (deterministic exit code on the first failure); pipelines that need parallelism should fan out via xargs -P at the shell layer rather than burying threading in the CLI. End-to-end overhead per file: parse + serialise dominates; argv parsing and file I/O are negligible (<1 ms) for files up to a few MiB.

Security

#![forbid(unsafe_code)] (workspace lint). No FFI. No network I/O. The binaries only read files passed on argv; they do not read environment variables. Resource-limit gates are inherited from noyalib’s ParserConfig defaults; pass --strict to opt into the tighter ParserConfig::strict() preset. Full posture: SECURITY.md.

API stability and SemVer

Pre-1.0 (0.0.x): the argv contract (long flags, exit codes, stdin/stdout shape) is stable within a 0.0.x line — bug fixes only. Adding a new flag is allowed within a 0.0.x bump; removing or renaming a flag, or repurposing an exit code, is held to a 0.x bump (e.g. 0.0.x → 0.1.0). The Rust library surface (NoyafmtCli, NoyavalidateCli, noyafmt_command, noyavalidate_command) is also covered by the workspace SemVer policy in POLICIES.md. cargo-semver-checks runs in CI on every PR and blocks accidental SemVer-incompatible changes.

Documentation

• Engineering policies — workspace POLICIES.md covers MSRV, SemVer, security, performance, concurrency, platform support, feature flags.
• CLI flag reference: doc/cli-reference.md.
• Recipes (pre-commit, CI gate, schema validation, k8s, Helm, Compose, GitHub Actions): the examples/ directory.

Structs

NoyafmtCli

CLI surface for noyafmt — the YAML formatter.

NoyavalidateCli

CLI surface for noyavalidate — the YAML validator.

Functions

noyafmt_command

Build the clap::Command for noyafmt.

noyavalidate_command

Build the clap::Command for noyavalidate.