cli: publish the finite option vocabularies through clap #198

Merged

natsukium merged 2 commits from feat/finite-option-values-187 into main 2026-09-07 21:29:43 +09:00

Conversation 0 Commits 2 Files changed 10 +950 -65

natsukium commented 2026-09-07 21:08:25 +09:00

Owner

Copy link

Fixes #187.

--format and capture --source parsed their values by hand, so clap published no possible values into --help, __mangen, or the generated completions. Both vocabularies are now ValueEnums (human|json, human|jsonl, and the four region sources), so one declaration reaches every published surface, and a bad value is refused with the list of what the verb accepts. felis bridge still takes the source vocabulary as a JSON string, so parse_region_source stays as that wrapper.

Help text itself gained a test: an insta snapshot walks the visible command tree and renders render_long_help() for the root and every subcommand, so a reworded flag or a lost possible value is a reviewed diff. A completion test asserts the zsh script carries the --format and --source values.

Doc cascade: docs/reference/cli.md names the possible values where it describes --format and capture --source; CHANGELOG.md records the user-visible help/completion change.

Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high

Deferred

• The last acceptance criterion — evidencing #55's two remaining closure criteria and closing the tracker: explicitly post-merge work on tracker #55, not code in this PR.

Fixes #187. `--format` and `capture --source` parsed their values by hand, so clap published no possible values into `--help`, `__mangen`, or the generated completions. Both vocabularies are now `ValueEnum`s (`human|json`, `human|jsonl`, and the four region sources), so one declaration reaches every published surface, and a bad value is refused with the list of what the verb accepts. `felis bridge` still takes the source vocabulary as a JSON string, so `parse_region_source` stays as that wrapper. Help text itself gained a test: an insta snapshot walks the visible command tree and renders `render_long_help()` for the root and every subcommand, so a reworded flag or a lost possible value is a reviewed diff. A completion test asserts the zsh script carries the `--format` and `--source` values. Doc cascade: `docs/reference/cli.md` names the possible values where it describes `--format` and `capture --source`; `CHANGELOG.md` records the user-visible help/completion change. Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high ## Deferred - The last acceptance criterion — evidencing #55's two remaining closure criteria and closing the tracker: explicitly post-merge work on tracker #55, not code in this PR.

natsukium added 2 commits 2026-09-07 21:08:25 +09:00

cli: publish the finite option vocabularies through clap ... 05c8aab78b

`--format` and `capture --source` parsed their values by hand, so clap
knew nothing about them: `--help`, the man page, and the generated
completions carried no possible values, and `--source <TAB>` fell back
to filenames. Modeling them as `ValueEnum`s makes the one vocabulary
reach every published surface at once.

The refusal for a bad value changes with it: clap lists the values the
verb takes instead of naming the sibling framing. Listing what is
accepted is the more useful half, and it is the half a reader cannot
get anywhere else once the message is the only thing on screen.

`felis bridge` takes the same source vocabulary as a JSON string rather
than through clap, so `parse_region_source` stays as the wrapper that
spells that refusal out.

Refs #187

cli: snapshot every visible help page ... 9ccce4bc5d

Help text is a published surface with no test behind it: a reworded
flag, a lost possible value, or a verb that stopped documenting where
its globals go all landed silently. One insta snapshot over the walked
command tree turns any of those into a reviewed diff.

clap's generated `help` subcommand is skipped: it mirrors the same
pages one indirection out, tripling the snapshot without adding a
surface a reader can change.

Refs #187

natsukium merged commit 1f8fa55cf1 into main 2026-09-07 21:29:43 +09:00

natsukium deleted branch feat/finite-option-values-187 2026-09-07 21:29:43 +09:00

natsukium referenced this pull request 2026-09-08 01:39:59 +09:00

[v0.1/CLI Args Review] CLI 引数のリリース前設計レビュー #55

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!198

No description provided.