Sandbox::https://github.com/jdx/usage/pull/1551

jdx · 2026-10-14T16:53:32Z

https://entire.io/gh/jdx/usage/trails/92

Binaries that embed usage-argv carry its help, completion and error rendering. In the oxlint and oxfmt migration to usage-rs, that was about +98 KB and +86 KB over their bpaf builds. This shrinks the code behind those paths without changing any output.

What changed

Almost all of it is the same few ideas applied across help.rs, help/template.rs, complete.rs, diagnostic.rs, lib.rs and spec.rs:

Appends go through shared out-of-line helpers (argv/src/text.rs). An inlined String::push_str costs about 100–130 bytes of code, and help text is built from hundreds of small appends. This was the largest single saving, about 12 KB.
Plain loops replace iterator adapter chains and closures in the flag walk, completion lists, help sections and usage lines. Each chain was monomorphised at every call site.
Characters are counted by one non-inlined routine instead of an expansion at each of 15 width calculations (about 8.6 KB).
Parse errors are written from templates with holes instead of per-site format!, and share one three-piece error line and one sigil-without-value error.
Flag spellings in help are compared as values (Form) rather than as formatted strings, and span tables live in statics.
The derive collects args_os once for both the completion intercept and the parse.

Help, -h, error, completion, spec and version output are unchanged byte for byte (plain, forced colour, and at width 200 on oxfmt's real CLI), and the whole conformance corpus passes. Several things that did not help were tried and left out: #[cold], #[inline(never)] on cold helpers, and replacing format! with &str arrays (that one grew the binary).

Measured

tasks/size.sh origin/main (stripped release builds):

binary	base	head	change
`usage` CLI	11,470,512	11,415,760	-54,752 (-0.48%)
derived mise CLI, usage's share	941,584	930,640	-10,944 (-1.16%)

On the oxc PR's CLIs (cargo build --release -p oxlint -p oxfmt, linux x86_64, same machine and toolchain, usage-argv patched in from this checkout in both builds): main → this branch is oxlint 14,960,504 → 14,927,736 B (-32,768) and oxfmt 9,295,640 → 9,258,776 B (-36,864). That recovers roughly a third to nearly half of what usage adds to those binaries over their bpaf builds (+98,304 and +86,016 B). Absolute sizes from a path-patched build run about 24 KB above the crates.io build of the same source, so compare the deltas, not the absolutes.

Speed: interleaved, minimum-of-N timings of oxfmt startup (--help, -h, --version, a bad flag, __complete_word__) show no change; the parse hot path is not touched. Parse instruction count on use -g node@20 is 8,425 at base and 8,433 here (+0.1%), and wall time is flat at about 428 ns. Recursive help and KDL rendering measured +1–2.5% in one run, attributed to the character count no longer being inlined; those are cold paths.

Notes for review

The history is kept as small commits, one idea each, so each can be reviewed or reverted alone. Changes that need public field types to shrink (flag and command tables) would break the API; they are recorded for 8.0 in V8.md (#1550).

This description was generated by Claude Code.

🤖 Generated with Claude Code

AI-assisted — Tool: Claude Code; model: anthropic/claude-sonnet-5-5; version: unavailable.

Note

Low Risk
Refactor of cold-path string rendering with stated byte-for-byte output parity and conformance tests; no auth or data-handling changes.

Overview
Shrinks embedded usage-argv binary footprint for help, shell completion, and parse-error rendering by centralizing string work and avoiding per-call-site monomorphization—without changing rendered output.

Adds argv/src/text.rs with shared out-of-line helpers (push_all, char_count, same_name, split_once_eq, etc.) and routes help, completion, diagnostics, and spec code through them. Help drops write!/format! in favor of a PutStr trait, streaming wrap_lines, and flag spellings as Form (long/short) instead of allocating --name strings. Diagnostics use put_template / error_with hole templates and delegate stderr colour to help::Style::auto_stderr. Completion gains keep_prefixed, offer, explicit loops where iterator chains duplicated codegen, and crate::has_str / has_byte for alias checks.

Help template rendering applies palette mapping inside AnsiStyle::apply and writes semantics via semantic_into; invalid templates fall back to section substitution only.

^{Reviewed by Cursor Bugbot for commit 12e27eb. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

Improvements
- Completion matching now selects the longest matching sigil, with later declarations taking precedence when matches are equally long.
- Help templates support palette-defined combined styles. Invalid style markup is displayed literally while placeholders are still substituted.
- Diagnostic color selection now follows the same automatic color policy as help output.
- Help and diagnostic output retain their existing wording and formats.

Help rows, usage lines and annotations were assembled with write! and format!, which pulls core::fmt argument handling into every call site. Plain pushes through small out-of-line helpers produce the same bytes and a smaller binary. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

own_and_global built a String for every long and short spelling just to test membership. A small Form enum compares them in place. Also drives the ANSI style lookup from the published STYLES table. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

wrap returned a Vec<String> that every caller walked once. One wrapping routine now hands each line to the writer, so the three callers share it and none of them allocates the intermediate lines. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

The sections-only fallback duplicated the template scanner and the blank-run collapse. One loop now serves both. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>