Skip to content

Commit 7eaf4a2

Browse files
molisanimolisani
committed
feat: new option to display brief with custom usage
Signed-off-by: Michael Molisani <[email protected]>
1 parent f237e04 commit 7eaf4a2

File tree

5 files changed

+498
-5
lines changed

5 files changed

+498
-5
lines changed

‎packages/core/src/routing/command/documentation.ts

+13-3
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@ import { formatDocumentationForPositionalParameters } from "../../parameter/posi
66
import type { CommandParameters } from "../../parameter/types";
77
import type { HelpFormattingArguments } from "../types";
88

9+
export interface CustomUsage {
10+
readonly input: string;
11+
readonly brief: string;
12+
}
13+
914
export interface CommandDocumentation {
1015
/**
1116
* In-line documentation for this command.
@@ -18,7 +23,7 @@ export interface CommandDocumentation {
1823
/**
1924
* Sample usage to replace the generated usage lines.
2025
*/
21-
readonly customUsage?: readonly string[];
26+
readonly customUsage?: readonly (string | CustomUsage)[];
2227
}
2328

2429
/**
@@ -34,8 +39,13 @@ export function* generateCommandHelpLines(
3439
const prefix = args.prefix.join(" ");
3540
yield args.ansiColor ? `\x1B[1m${headers.usage}\x1B[22m` : headers.usage;
3641
if (customUsage) {
37-
for (const customUsageLine of customUsage) {
38-
yield ` ${prefix} ${customUsageLine}`;
42+
for (const usage of customUsage) {
43+
if (typeof usage === "string") {
44+
yield ` ${prefix} ${usage}`;
45+
} else {
46+
const brief = args.ansiColor ? `\x1B[3m${usage.brief}\x1B[23m` : usage.brief;
47+
yield ` ${prefix} ${usage.input}\n ${brief}`;
48+
}
3949
}
4050
} else {
4151
yield ` ${formatUsageLineForParameters(parameters, args)}`;

‎packages/core/tests/application.spec.ts

+60-1
Original file line numberDiff line numberDiff line change
@@ -674,7 +674,7 @@ describe("Application", () => {
674674
},
675675
docs: {
676676
brief: "basic command",
677-
customUsage: ["custom usage 1", "custom usage 2", "custom usage 3"],
677+
customUsage: ["custom usage 1", { input: "custom-two", brief: "enhanced custom usage 2" }, "custom usage 3"],
678678
},
679679
});
680680
const appWithAlternateUsage = buildApplication(commandWithAlternateUsage, {
@@ -1526,6 +1526,65 @@ describe("Application", () => {
15261526
compareToBaseline(this, ApplicationRunResultBaselineFormat, result);
15271527
});
15281528
});
1529+
1530+
describe("nested basic route map with hidden routes, always show help-all (alias)", () => {
1531+
// GIVEN
1532+
const rootRouteMap = buildRouteMapForFakeContext({
1533+
routes: {
1534+
sub: buildBasicRouteMap("sub"),
1535+
subHidden: buildBasicRouteMap("subHidden"),
1536+
},
1537+
docs: {
1538+
brief: "root route map",
1539+
hideRoute: {
1540+
subHidden: true,
1541+
},
1542+
},
1543+
});
1544+
const app = buildApplication(rootRouteMap, {
1545+
name: "cli",
1546+
documentation: {
1547+
alwaysShowHelpAllFlag: true,
1548+
useAliasInUsageLine: true,
1549+
},
1550+
});
1551+
1552+
// WHEN
1553+
it("display help text for root (implicit)", async function () {
1554+
const result = await runWithInputs(app, []);
1555+
compareToBaseline(this, ApplicationRunResultBaselineFormat, result);
1556+
});
1557+
1558+
it("display help text for root", async function () {
1559+
const result = await runWithInputs(app, ["--help"]);
1560+
compareToBaseline(this, ApplicationRunResultBaselineFormat, result);
1561+
});
1562+
1563+
it("display help text for root including hidden", async function () {
1564+
const result = await runWithInputs(app, ["--help-all"]);
1565+
compareToBaseline(this, ApplicationRunResultBaselineFormat, result);
1566+
});
1567+
1568+
it("fails for undefined route", async function () {
1569+
const result = await runWithInputs(app, ["undefined"]);
1570+
compareToBaseline(this, ApplicationRunResultBaselineFormat, result);
1571+
});
1572+
1573+
it("fails for undefined flag", async function () {
1574+
const result = await runWithInputs(app, ["--undefined"]);
1575+
compareToBaseline(this, ApplicationRunResultBaselineFormat, result);
1576+
});
1577+
1578+
it("displays help text for nested hidden route map (implicit)", async function () {
1579+
const result = await runWithInputs(app, ["subHidden"]);
1580+
compareToBaseline(this, ApplicationRunResultBaselineFormat, result);
1581+
});
1582+
1583+
it("displays help text for nested hidden route map", async function () {
1584+
const result = await runWithInputs(app, ["subHidden", "--help"]);
1585+
compareToBaseline(this, ApplicationRunResultBaselineFormat, result);
1586+
});
1587+
});
15291588
});
15301589

15311590
describe("proposeCompletions", () => {

‎packages/core/tests/baselines/reference/application.txt

+113-1
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,8 @@ ExitCode=Success
245245
:: STDOUT
246246
USAGE
247247
cli custom usage 1
248-
cli custom usage 2
248+
cli custom-two
249+
enhanced custom usage 2
249250
cli custom usage 3
250251
cli --help
251252

@@ -1085,6 +1086,117 @@ ExitCode=UnknownCommand
10851086
:: STDERR
10861087
No command registered for `undefined`
10871088

1089+
:::: Application / run / nested basic route map with hidden routes, always show help-all (alias) / display help text for root
1090+
ExitCode=Success
1091+
:: STDOUT
1092+
USAGE
1093+
cli sub command ...
1094+
cli -h
1095+
cli -H
1096+
1097+
root route map
1098+
1099+
FLAGS
1100+
-h --help Print help information and exit
1101+
-H --helpAll Print help information (including hidden commands/flags) and exit
1102+
1103+
COMMANDS
1104+
sub sub
1105+
1106+
:: STDERR
1107+
1108+
:::: Application / run / nested basic route map with hidden routes, always show help-all (alias) / display help text for root (implicit)
1109+
ExitCode=Success
1110+
:: STDOUT
1111+
USAGE
1112+
cli sub command ...
1113+
cli -h
1114+
cli -H
1115+
1116+
root route map
1117+
1118+
FLAGS
1119+
-h --help Print help information and exit
1120+
-H --helpAll Print help information (including hidden commands/flags) and exit
1121+
1122+
COMMANDS
1123+
sub sub
1124+
1125+
:: STDERR
1126+
1127+
:::: Application / run / nested basic route map with hidden routes, always show help-all (alias) / display help text for root including hidden
1128+
ExitCode=Success
1129+
:: STDOUT
1130+
USAGE
1131+
cli sub command ...
1132+
cli subHidden command ...
1133+
cli -h
1134+
cli -H
1135+
1136+
root route map
1137+
1138+
FLAGS
1139+
-h --help Print help information and exit
1140+
-H --helpAll Print help information (including hidden commands/flags) and exit
1141+
1142+
COMMANDS
1143+
sub sub
1144+
subHidden subHidden
1145+
1146+
:: STDERR
1147+
1148+
:::: Application / run / nested basic route map with hidden routes, always show help-all (alias) / displays help text for nested hidden route map
1149+
ExitCode=Success
1150+
:: STDOUT
1151+
USAGE
1152+
cli subHidden command
1153+
cli subHidden -h
1154+
cli subHidden -H
1155+
1156+
subHidden
1157+
1158+
FLAGS
1159+
-h --help Print help information and exit
1160+
-H --helpAll Print help information (including hidden commands/flags) and exit
1161+
1162+
COMMANDS
1163+
command basic command
1164+
1165+
:: STDERR
1166+
1167+
:::: Application / run / nested basic route map with hidden routes, always show help-all (alias) / displays help text for nested hidden route map (implicit)
1168+
ExitCode=Success
1169+
:: STDOUT
1170+
USAGE
1171+
cli subHidden command
1172+
cli subHidden -h
1173+
cli subHidden -H
1174+
1175+
subHidden
1176+
1177+
FLAGS
1178+
-h --help Print help information and exit
1179+
-H --helpAll Print help information (including hidden commands/flags) and exit
1180+
1181+
COMMANDS
1182+
command basic command
1183+
1184+
:: STDERR
1185+
1186+
:::: Application / run / nested basic route map with hidden routes, always show help-all (alias) / fails for undefined flag
1187+
ExitCode=UnknownCommand
1188+
:: STDOUT
1189+
1190+
:: STDERR
1191+
No command registered for `--undefined`
1192+
1193+
:::: Application / run / nested basic route map with hidden routes, always show help-all (alias) / fails for undefined route
1194+
ExitCode=UnknownCommand
1195+
:: STDOUT
1196+
1197+
:: STDERR
1198+
No command registered for `undefined`
1199+
10881200
:::: Application / run / nested basic route map with hidden routes, always show help-all / display help text for root
10891201
ExitCode=Success
10901202
:: STDOUT

‎packages/core/tests/baselines/reference/routing/command.txt

+75
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,26 @@ USAGE
256256

257257
brief
258258

259+
FLAGS
260+
-a --alpha alpha flag brief
261+
--bravo... bravo flag brief
262+
[--charlie] charlie flag brief
263+
-d --delta/--noDelta delta flag brief
264+
-h --help Print help information and exit
265+
266+
ARGUMENTS
267+
args... string array brief
268+
269+
:::: Command / printHelp / mixed parameters, enhanced custom usage
270+
USAGE
271+
prefix -a 1
272+
enhanced usage line #1
273+
prefix -a 2 -d
274+
enhanced usage line #2
275+
prefix --help
276+
277+
brief
278+
259279
FLAGS
260280
-a --alpha alpha flag brief
261281
--bravo... bravo flag brief
@@ -307,6 +327,49 @@ USAGE
307327

308328
Longer description of this command's behavior, only printed during --help
309329

330+
FLAGS
331+
-a --alpha alpha flag brief
332+
--bravo... bravo flag brief
333+
[--charlie] charlie flag brief
334+
-d --delta/--noDelta delta flag brief
335+
-h --help Print help information and exit
336+
337+
ARGUMENTS
338+
args... string array brief
339+
340+
:::: Command / printHelp / mixed parameters, help all, force alias in usage line
341+
USAGE
342+
prefix (-a value) (--bravo value)... [--charlie c] (-d) <args>...
343+
prefix -h
344+
prefix -H
345+
346+
brief
347+
348+
FLAGS
349+
-a --alpha alpha flag brief
350+
--bravo... bravo flag brief
351+
[--charlie] charlie flag brief
352+
-d --delta/--noDelta delta flag brief
353+
-h --help Print help information and exit
354+
-H --helpAll Print help information (including hidden commands/flags) and exit
355+
356+
ARGUMENTS
357+
args... string array brief
358+
359+
:::: Command / printHelp / mixed parameters, mixed custom usage
360+
USAGE
361+
prefix -a 1
362+
enhanced usage line #1
363+
prefix normal custom usage A
364+
prefix normal custom usage B
365+
prefix -a 2 -d
366+
enhanced usage line #2
367+
prefix normal custom usage C
368+
prefix normal custom usage D
369+
prefix --help
370+
371+
brief
372+
310373
FLAGS
311374
-a --alpha alpha flag brief
312375
--bravo... bravo flag brief
@@ -442,6 +505,18 @@ brief
442505
FLAGS
443506
-h --help Print help information and exit
444507

508+
:::: Command / printHelp / no parameters, help all, force alias in usage line
509+
USAGE
510+
prefix
511+
prefix -h
512+
prefix -H
513+
514+
brief
515+
516+
FLAGS
517+
-h --help Print help information and exit
518+
-H --helpAll Print help information (including hidden commands/flags) and exit
519+
445520
:::: Command / run / command function returns error / with custom exit code
446521
ExitCode=Unknown(10)
447522
:: STDOUT

0 commit comments

Comments
 (0)