Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
314 changes: 237 additions & 77 deletions argv/src/help.rs

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion conformance/tests/admonitions.rs
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ fn semantic_blocks_survive_flattened_and_nested_value_layouts() {

let portable_terminal = usage::docs::cli::render_help(&spec, &spec.cmd, true);
assert!(
portable_terminal.contains("Note: Nested value first.\n\n Nested value last."),
portable_terminal.contains("Note: Nested value first.\n\n Nested value last."),
"{portable_terminal:?}"
);
assert!(
Expand Down
104 changes: 95 additions & 9 deletions conformance/tests/metadata.rs
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,79 @@ struct CappedColumns {
threads: Option<usize>,
}

#[derive(Cli)]
#[usage(
bin = "oxlint-layout",
term_width = 80,
about = "A fast JavaScript and TypeScript linter with a deliberately long introduction that must wrap cleanly"
)]
#[allow(dead_code)]
struct OxcHelpLayout {
/// Do not fail when a supplied pattern matches no files
#[usage(long)]
no_error_on_unmatched_pattern: bool,
/// Disable the TypeScript language service plugin
#[usage(long)]
disable_typescript_plugin: bool,
/// Add a pattern to the ignore list while retaining every previously configured pattern
#[usage(long, value_name = "PATTERN")]
ignore_pattern: Vec<String>,
#[usage(
long,
value_name = "OPTIONS",
help = "Enable debug output for selected subsystems",
long_help = "Enable debug output for selected subsystems.\n\n- parser: trace parsed files and recovered syntax\n- resolver: trace module resolution and cache decisions"
)]
debug: Option<String>,
#[usage(
long,
value_name = "PATH",
help = "Use a configuration file",
long_help = "Use a configuration file. Configuration discovered from parent directories is merged first.\n\nWarning: explicit files replace project-local defaults.\n\n oxlint-layout --config ./oxlint.json"
)]
config: Option<String>,
}

#[test]
fn oxc_shaped_help_keeps_useful_prose_inline_and_wraps_the_rest() {
let spec = OxcHelpLayout::spec();
let portable: LibSpec = OxcHelpLayout::to_kdl().parse().expect("valid spec");

for long in [false, true] {
let page = usage_argv::help::render(spec, spec.root.cmd, long).unwrap();
assert_eq!(
page,
usage::docs::cli::render_help(&portable, &portable.cmd, long)
);
assert!(page.lines().any(|line| {
line.contains("--no-error-on-unmatched-pattern") && line.contains("Do not fail when")
}));
assert!(page.lines().any(|line| {
line.contains("--disable-typescript-plugin") && line.contains("Disable the TypeScript")
}));
assert!(page.lines().all(|line| !line.ends_with(' ')), "{page}");
for line in page.lines() {
if !line.trim_start().starts_with("oxlint-layout --config")
&& !line.starts_with("Usage:")
{
assert!(
line.chars().count() <= 80,
"line exceeds width: {line:?}\n{page}"
);
}
}
}

let long = usage_argv::help::render(spec, spec.root.cmd, true).unwrap();
assert!(long.contains("\n\n"), "{long}");
assert!(long.contains("- parser:"), "{long}");
assert!(long.contains("- resolver:"), "{long}");
assert!(
long.contains(" oxlint-layout --config ./oxlint.json"),
"{long}"
);
}

#[derive(Args)]
#[usage(disable_help_flag, term_width = 0)]
#[allow(dead_code)]
Expand Down Expand Up @@ -145,17 +218,30 @@ fn flattened_help_caps_each_nested_commands_columns_too() {
}),
"{page}"
);
assert!(
page.contains("--report-unused-disable-directives-severity <SEVERITY>\n Choose the severity for unused directives while keeping every long\n explanation inside the bounded parent help page"),
"{page}"
let lines = page.lines().collect::<Vec<_>>();
let severity = lines
.iter()
.position(|line| line.contains("--report-unused-disable-directives-severity"))
.expect("severity flag");
assert_eq!(
lines[severity + 1].trim(),
"Choose the severity for unused directives"
);
assert!(
page.contains("--an-extraordinarily-long-multiline-option-name\n Keep this line.\n And this one."),
"{page}"
assert_eq!(
lines[severity + 2].trim(),
"while keeping every long explanation inside"
);
let multiline = lines
.iter()
.position(|line| line.contains("--an-extraordinarily-long-multiline-option-name"))
.expect("multiline flag");
assert_eq!(lines[multiline + 1].trim(), "Keep this line.");
assert_eq!(lines[multiline + 2].trim(), "And this one.");
if !long {
assert!(
page.contains("[env: COLUMN_CAP_SEVERITY]") && page.contains("(default: warn)"),
page.contains("[env:")
&& page.contains("COLUMN_CAP_SEVERITY]")
&& page.contains("(default: warn)"),
"{page}"
);
}
Expand All @@ -169,7 +255,7 @@ fn flattened_help_caps_each_nested_commands_columns_too() {
}

#[test]
fn a_long_command_name_only_moves_its_own_wrapped_summary_below() {
fn a_long_command_name_keeps_help_inline_when_useful_room_remains() {
let spec = CappedCommandColumns::spec();
let portable: LibSpec = CappedCommandColumns::to_kdl().parse().expect("valid spec");

Expand All @@ -180,7 +266,7 @@ fn a_long_command_name_only_moves_its_own_wrapped_summary_below() {
usage::docs::cli::render_help(&portable, &portable.cmd, long)
);
assert!(
page.contains("an-extraordinarily-long-subcommand-name\n Explain this unusually named command with enough detail to wrap beneath its\n name on a bounded help page"),
page.contains("an-extraordinarily-long-subcommand-name Explain this unusually named command\n with enough detail to wrap beneath\n its name on a bounded help page"),
"{page}"
);
}
Expand Down
30 changes: 17 additions & 13 deletions go/argv/page.go
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,8 @@ func ShortHelp(spec HelpSpec, path []string, chain []*Command, help HelpTable) s
before = meta.BeforeHelp
}
if before != "" {
out.WriteString(before + "\n\n")
writeWrapped(out, before, 0)
out.WriteString("\n")
}

// The program, then what it is for — on the program's own page. A
Expand All @@ -117,10 +118,12 @@ func ShortHelp(spec HelpSpec, path []string, chain []*Command, help HelpTable) s
// under a description belongs to the renderer, so one already in the text is a
// second one.
if about := trimEnd(about); about != "" {
out.WriteString(about + "\n\n")
writeWrapped(out, about, 0)
out.WriteString("\n")
}
if label := deprecationLabel(meta); label != "" {
out.WriteString(label + "\n\n")
writeWrapped(out, label, 0)
out.WriteString("\n")
}

for i, line := range usageLines(path, cmd, help) {
Expand Down Expand Up @@ -157,7 +160,7 @@ func ShortHelp(spec HelpSpec, path []string, chain []*Command, help HelpTable) s
if nextLineHelp {
w.WriteString(" " + usage + "\n")
if text := helpText(h); text != "" {
writeIndented(w, text, 4)
writeWrapped(w, text, 4)
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
}
longAnnotations(w, h, true, blockIndent)
return
Expand Down Expand Up @@ -190,7 +193,7 @@ func ShortHelp(spec HelpSpec, path []string, chain []*Command, help HelpTable) s
if nextLineHelp {
w.WriteString(" " + f.usage + "\n")
if text := f.suppliedHelp; text != "" {
writeIndented(w, text, 4)
writeWrapped(w, text, 4)
}
return
}
Expand All @@ -200,7 +203,7 @@ func ShortHelp(spec HelpSpec, path []string, chain []*Command, help HelpTable) s
if nextLineHelp {
w.WriteString(" " + f.usage + "\n")
if text := metaField(h, func(x *Help) string { return x.Short }); text != "" {
writeIndented(w, text, 4)
writeWrapped(w, text, 4)
}
longAnnotations(w, h, true, blockIndent)
return
Expand Down Expand Up @@ -234,7 +237,8 @@ func ShortHelp(spec HelpSpec, path []string, chain []*Command, help HelpTable) s
after = meta.AfterHelp
}
if after != "" {
sections.afterHelp.WriteString("\n" + after + "\n")
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
sections.afterHelp.WriteString("\n")
writeWrapped(&sections.afterHelp, after, 0)
}

return sections.assemble(spec.HelpTemplate)
Expand Down Expand Up @@ -324,7 +328,7 @@ func commandsSection(out *strings.Builder, path []string, cmd *Command, help Hel
if long && section != "" {
if proseOf := headingProse(help.Lookup(cmd.Key)); proseOf != nil {
if prose := proseOf(section); prose != "" {
writeIndented(out, prose, 2)
writeWrapped(out, prose, 2)
out.WriteString("\n")
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
}
}
Expand Down Expand Up @@ -384,10 +388,10 @@ func flatCommandsShort(out *strings.Builder, path []string, cmd *Command, help H
subPath := append(append([]string{}, path...), sub.Name)
out.WriteString("\n" + strings.Join(subPath, " ") + ":\n")
if text := metaField(h, func(x *Help) string { return x.Short }); strings.TrimSpace(text) != "" {
out.WriteString(trimEnd(text) + "\n")
writeWrapped(out, trimEnd(text), 0)
}
if label := deprecationLabel(h); label != "" {
out.WriteString(label + "\n")
writeWrapped(out, label, 0)
}

args := visibleArgs(sub, help, false)
Expand All @@ -414,7 +418,7 @@ func flatCommandsShort(out *strings.Builder, path []string, cmd *Command, help H
if nextLine {
out.WriteString(" " + usage + "\n")
if text := metaField(ah, func(x *Help) string { return x.Short }); text != "" {
writeIndented(out, text, 4)
writeWrapped(out, text, 4)
}
longAnnotations(out, ah, true, blockIndent)
} else {
Expand All @@ -427,7 +431,7 @@ func flatCommandsShort(out *strings.Builder, path []string, cmd *Command, help H
if nextLine {
out.WriteString(" " + usage + "\n")
if text := metaField(fh, func(x *Help) string { return x.Short }); text != "" {
writeIndented(out, text, 4)
writeWrapped(out, text, 4)
}
longAnnotations(out, fh, true, blockIndent)
} else {
Expand Down Expand Up @@ -475,7 +479,7 @@ func groupsSection(out, ungrouped, grouped *strings.Builder, defaultTitle string
section.WriteString("\n" + title + ":\n")
if heading != "" && proseOf != nil {
if prose := proseOf(heading); prose != "" {
writeIndented(&section, prose, 2)
writeWrapped(&section, prose, 2)
section.WriteString("\n")
}
}
Expand Down
Loading
Loading