[pull] main from fern-api:main - #909
Merged
Merged
Conversation
… help lines concise (#17476) * feat(cli-generator): use OpenAPI root tag descriptions for CLI group help Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fix(cli-generator): preserve group descriptions in agent skills Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * feat(cli-generator): refine OpenAPI group descriptions Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * feat(cli): improve OpenAPI group help descriptions Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fix(cli-generator): keep method detail in long help and stop cutting help at abbreviations `<method> --help` rendered only the truncated table line, so the rest of an operation's description was unreachable anywhere in the CLI. Methods now set `long_about` with the fuller prose, capped at CLI_DESCRIPTION_LIMIT so a verbose spec cannot flood the terminal. The table line stays a single short sentence, and `long_about` is omitted when it would only repeat it. Sentence splitting was a bare `find(". ")`, so `e.g.`, `i.e.` and `U.S.` cut help text mid-phrase — on every method line, since the 80-char table cap now routes all descriptions through it. `first_sentence` and the pre-existing `find_last_sentence_boundary` (which does its own boundary search on the truncation path, and had the same bug) now share an `is_sentence_boundary` predicate rejecting dotted abbreviations, single-letter initials, a known abbreviation list, and any period followed by a lowercase word. Regenerates the vendored CLI runtime copies under seed/. Co-Authored-By: Claude <noreply@anthropic.com> * fix(cli-generator): stop a sibling tag from naming a group it only partly covers Found testing against ElevenLabs' real spec: the `voices` group rendered "Create and manage Professional Voice Clones (PVCs)." Its operations carry both `voices` (12 ops, no root description) and `pvc-voices` (14 ops, documented, exclusive to the group), so `pvc-voices` cleared the coverage majority and named the whole group after one of its features. Two rules, both narrowing what can be borrowed: - A tag named after the group owns that group's description. When the group's operations declare it, it is the only tag allowed to describe them — the name-match loop above already returned if it carries prose, so reaching the coverage branch means the group genuinely documents nothing and must fall back to the generic label rather than borrow from a sibling. - A described tag the group declares less often than another describes part of the group, so it cannot name the whole group even when it clears the coverage majority. Verified against the customer spec: exactly one group line changes, the wrong one. The remaining non-generic lines are unchanged. Co-Authored-By: Claude <noreply@anthropic.com> * feat(cli-generator): let x-fern-groups description drive the group table line `description` alone (no `summary`) left the command table showing `Operations on '<name>'`, with the prose reachable only from `--help`. That asymmetry stopped making sense once tag prose could reach the table: a group with no Fern configuration at all now gets a real table line from its tag, while a group whose owner had written a description explicitly did not. `description` is the more authoritative of the two, so it now resolves ahead of tag prose for `about` — the precedence the agent-skill emitter already applied, so the CLI table and the emitted skill no longer disagree. Only the first sentence reaches the table; `long_about` keeps the full text and is omitted when it would merely repeat it. This also gives users a lever that does not disturb Docs or SDKs: in `buildServices.ts`, `summary` sets a subpackage's `display-name` (a rename) while `description` sets its `docs`, so a description-only override corrects group help everywhere without relabelling anything. Reverses the behavior pinned by test_group_description_sets_long_about_only from #16034; the test is retained under a new name recording the rationale. Co-Authored-By: Claude <noreply@anthropic.com> * feat(cli-generator): keep an operation's prose instead of only its summary The parser collapsed two distinct OpenAPI fields into one: let description = operation.summary.clone() .or_else(|| operation.description.clone()); `RestMethod` carried a single `description`, and both the command table entry and the command's own `--help` body were derived from it. When an operation had a terse `summary` and a richer `description` the prose was dropped at parse time and was unreachable anywhere in the CLI — so the `long_about` added earlier in this branch had nothing better to show than the table line. `RestMethod` now carries `long_description` alongside it, holding the operation's `description` when it says more than the summary, and `None` when it would only duplicate it. The table line is unchanged; `<command> --help` renders the prose. Capped at a new `CLI_LONG_DESCRIPTION_LIMIT` (600) rather than the 200-char `CLI_DESCRIPTION_LIMIT` used for flag help: this body only appears when the user asks for one specific command. Measured against a real 336-operation spec, 200 would cut 23 descriptions mid-sentence while 600 covers 333 of 335. On that spec, 80 of 128 top-level leaf commands now show prose under `--help` that previously appeared nowhere. Co-Authored-By: Claude <noreply@anthropic.com> * fix(cli-generator): make -h a summary again instead of a second --help `-h` and `--help` printed the same flag help, so a request with 40 documented fields rendered ~9.6k characters either way and neither view was scannable. clap already gives two tiers; the generator was only filling one. Flags now set `help` to a one-line form (first sentence, capped at CLI_SHORT_DESCRIPTION_LIMIT) and `long_help` to the fuller prose, with the long form omitted when it would only repeat the short one. Annotations — availability badge, `(api: <wire name>)`, `[default: ...]` — are applied to both tiers through one shared closure rather than being duplicated. Two related defects in the same path: - `build_multipart_field_arg` set `.help(desc.clone())` with no truncation, while every other parameter went through `truncate_description`. A single multipart operation could emit several hundred characters for one flag. - Spec prose carrying hand-indentation from YAML block scalars reached the help column verbatim, showing as long gaps mid-sentence. `collapse_whitespace` now normalizes it. Measured on a real 46-flag multipart operation: `-h` 9,602 -> 3,657 chars, `--help` 10,089 -> 6,345. Operations whose parameters already fit are unchanged. Co-Authored-By: Claude <noreply@anthropic.com> * fix(cli-generator): let --help keep a flag's full documentation The two-tier split capped the long tier at CLI_DESCRIPTION_LIMIT (200), which cut exactly the clauses that make `--help` worth reading — constraints, character limits, pricing surcharges, examples. `-h` is the tier that should trim; `--help` is the thorough one and should truncate nothing a real spec contains. CLI_LONG_DESCRIPTION_LIMIT is raised to 2000 and now bounds both a command's own description and its flags'. It is a guard against a pathological spec flooding the terminal, not an editorial trim: the longest parameter description in a real 885-parameter spec is 560 characters. Measured on `speech-to-text convert`, where 19 flags exceed the old 200-char cap: --keyterms -h A list of keyterms to bias the transcription towards. --help 628 chars, through "...a minimum billable duration of 20 seconds applies per request." `-h` stays at 3,657 chars (down from 9,602); `--help` is 10,224, close to the original 10,089 because that tier is meant to be complete. Co-Authored-By: Claude <noreply@anthropic.com> * fix(cli-generator): don't promote a description that only paraphrases the summary Keeping an operation's `description` for `--help` assumed it elaborates on `summary`. Often it just says the same thing differently: -h List workspace groups --help Get all groups in the workspace which reads as two different commands rather than a summary and its detail. On a real 336-operation spec this was the majority: 192 of 335 operations carrying both fields have a description within 40 characters of the summary. A description now earns the long slot only by adding a further sentence or a substantial clause (40+ characters). Otherwise `--help` shows the same header as `-h`, which is what it did before the field split. On that spec, 150 leaf commands still elaborate and 187 repeat the short line. This narrows f8966ca rather than reverting it: descriptions that genuinely document an operation — webhook semantics, deprecation notices, pricing — are still the ones that reach `--help`. Co-Authored-By: Claude <noreply@anthropic.com> * chore(cli-generator): regenerate cli seed fixtures Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * Revert "chore(cli-generator): regenerate cli seed fixtures" This reverts commit 59b98bc. --------- Co-authored-by: rishabh.dhadda <rishabh.dhadda@postman.com> Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See Commits and Changes for more details.
Created by
pull[bot] (v2.0.0-alpha.4)
Can you help keep this open source service alive? 💖 Please sponsor : )