feat(parse): support non-strict choices

[jdx]

Summary

• add choices strict=#false and typed choices_strict = false declarations
• retain known values in help, completion, KDL, and generated metadata while accepting other values
• carry the policy through usage-lib, usage-argv tables/derive, JSON-to-Go lowering, and generated Go
• reject non-strict ValueEnum declarations because an unknown word cannot construct an enum variant
• document the feature, update the clap matrix, and close the PLAN gap

Verification

• mise run ci
• focused Rust and Go conformance tests

---

Note

Medium Risk
Changes post-parse choice validation across Rust and Go parsers. Default remains strict, so existing CLIs are unaffected unless they opt in.

Overview
Adds non-strict choices: declared values remain suggestions for help and completion, while values outside the list are accepted. Strict validation stays the default.

KDL uses choices strict=#false …; the derive uses choices_strict = false on a string-like field with choices(...). The policy is carried through usage-lib, argv metadata, generated Go tables, and KDL emission. Combining it with value_enum is a compile error, since an unknown word cannot construct an enum variant.

Docs and the clap matrix record this as usage-only (clap#5885).

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: df86c7dd-6394-4a3d-b434-f8aa274f309c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	█▁▁▃	199,315,003 → 201,371,612	+1.03% ⚠️	19.00 → 18.75ms	-1.31%
startup	▁▇▇█	1,221,718 → 1,223,027	+0.11%	1.35 → 1.36ms	+1.07%

1 benchmark(s) above the 1% gate: markdown +1.03%

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework	instructions, cold parse	vs usage
usage	4353	—
argh	6292	1.4x
clap	5893640	1353x
bpaf	21917948	5035x

                                              min       p01       p10    median
usage-rs: argv -> struct                      188       190       192       196  ns
argh: argv -> struct                          266       270       274       283  ns
clap: build tree + parse -> struct         472537    473456    477256    483644  ns
bpaf: build parser + parse -> struct      1588358   1588358   1601092   1646566  ns

usage: argv -> struct                             202 ns      0.20 µs
clap: build tree + parse -> struct             489659 ns    489.66 µs
clap: parse -> struct, tree reused              23054 ns     23.05 µs
clap: build tree only                          305124 ns    305.12 µs

_{434930e53568 vs c10d85cbe1b9 · measured on the runner, not pushed to the history.}