wip: abstract builtin arg parsing; clap/bpaf/usage backends

[lu-zero]

Summary

Redo of the wip/bpaf-engine experiment on top of current origin/main, importable in reviewable pieces:

• Engine-neutral contract: brush_core::args::{FromArgs, ArgsError}; builtins::Command: FromArgs with a transitional clap blanket impl and clap_content() help helper.
• Per-builtin split: logic stays in {builtin}.rs, engine structs live in {builtin}/{clap,bpaf,usage}.rs, selected by arg_impl! with global priority usage > bpaf > clap (per-builtin mixing explicitly deferred).
• Shared runtimes: args/bpaf_support.rs, args/usage_support.rs (plus-cluster expansion, option/trailing split, -- handling).
• Benchmark harness ported from bpaf-port (benchmarks/three-way.py + benchmarks/real-world/*, plus --numa-node pinning) with recorded results.

Verification (all pinned to NUMA node 3 / cpu 96)

• Compat suite, all three backends: 1971 passed / 0 failed (471 known-fail, 29 skipped).
• Abstraction zero-cost check (interleaved anchor-vs-abstract): pairwise medians 0.99-1.03x, RSS within 128 KiB.
• Three-backend shootout vs bash oracle, byte-identical outputs: benchmarks/results/backends-c986f537/ (parse-dense config-lint-500: usage 62ms, bpaf 79ms, clap 107ms).
• cargo fmt --check and cargo clippy clean for all three engine configs.

Notes for reviewers

• Conflict resolutions vs the original wip stack all favor current main: shared lookup framework (command, type), declare -I, read UTF-8 rework, printf %q rework.
• One genuine port gap fixed along the way: command -v/-V last-wins in both non-clap backends.
• interp-loop timing anomaly (usage inexplicably faster on a parse-free workload) needs a re-run before quoting.

Assisted-by: Muse Spark:muse-spark-1.3-contributor-free [opencode]

[github-actions]

Public API changes for crate: brush-core

Added items

+pub mod brush_core::args
+pub struct brush_core::args::ArgsError
+pub brush_core::args::ArgsError::help_request: bool
+pub brush_core::args::ArgsError::message: alloc::string::String
+impl brush_core::args::ArgsError
+pub fn brush_core::args::ArgsError::from_clap_error(&clap_builder::Error) -> Self
+pub fn brush_core::args::ArgsError::help(impl core::convert::Into<alloc::string::String>) -> Self
+pub fn brush_core::args::ArgsError::new(impl core::convert::Into<alloc::string::String>) -> Self
+impl core::error::Error for brush_core::args::ArgsError
+impl core::fmt::Display for brush_core::args::ArgsError
+pub fn brush_core::args::ArgsError::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub trait brush_core::args::FromArgs: core::marker::Sized
+pub fn brush_core::args::FromArgs::from_args(&[alloc::string::String]) -> core::result::Result<Self, brush_core::args::ArgsError>
+impl<T: clap_builder::derive::Parser> brush_core::args::FromArgs for T
+pub fn T::from_args(&[alloc::string::String]) -> core::result::Result<Self, brush_core::args::ArgsError>
+pub fn brush_core::builtins::clap_content<T: clap_builder::derive::Parser>(&str, &brush_core::builtins::ContentType, &brush_core::builtins::ContentOptions) -> core::result::Result<alloc::string::String, brush_core::error::Error>
+impl core::str::traits::FromStr for brush_core::completion::CompleteAction
+pub type brush_core::completion::CompleteAction::Err = alloc::string::String
+pub fn brush_core::completion::CompleteAction::from_str(&str) -> core::result::Result<Self, Self::Err>
+impl core::str::traits::FromStr for brush_core::completion::CompleteOption
+pub type brush_core::completion::CompleteOption::Err = alloc::string::String
+pub fn brush_core::completion::CompleteOption::from_str(&str) -> core::result::Result<Self, Self::Err>

Changed items

-pub trait brush_core::builtins::Command: clap_builder::derive::Parser
+pub trait brush_core::builtins::Command: brush_core::args::FromArgs
-pub fn brush_core::builtins::Command::new<I>(I) -> core::result::Result<Self, clap_builder::Error> where I: core::iter::traits::collect::IntoIterator<Item = alloc::string::String>
+pub fn brush_core::builtins::Command::new<I>(I) -> core::result::Result<Self, brush_core::args::ArgsError> where I: core::iter::traits::collect::IntoIterator<Item = alloc::string::String>

Performance Benchmark Report

Code Coverage Report: Only Changed Files listed

Package	Base Coverage	New Coverage	Difference
brush-builtins\src\bind.rs	🔴 25.17%	🔴 25.68%	🟢 0.51%
brush-builtins\src\printf.rs	🟠 52.38%	🟠 51.91%	🔴 -0.47%
brush-builtins\src\read.rs	🔴 36.49%	🔴 37.09%	🟢 0.6%
brush-core\src\args.rs	🔴 0%	🟢 92%	🟢 92%
brush-core\src\completion.rs	🔴 14.51%	🔴 13.85%	🔴 -0.66%
brush-test-harness\src\util.rs	🔴 5.66%	🔴 5.45%	🔴 -0.21%
Overall Coverage	🟢 27.74%	🟢 27.15%	🔴 -0.59%

Minimum allowed coverage is 20%, this run produced 27.15%
Maximum allowed coverage difference is -5%, this run produced -0.59%

Test Summary: bash-completion test suite

Outcome	Count	Percentage
✅ Pass	1586	75.20
❗️ Error	19	0.90
❌ Fail	151	7.16
⏩ Skip	338	16.03
❎ Expected Fail	13	0.62
✔️ Unexpected Pass	2	0.09
📊 Total	2109	100.00