[dartdev] Organize dart --help commands into categories (2)

dcharkes · Commit Queue · commit 59ed4ebde9b7 · 2025-06-25T08:39:04.000-07:00
TEST=pkg/dartdev/test/commands/help_test.dart Change-Id: I4e6eed1093412c8b307713c0faf95a84d56b5f26 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/436905 Reviewed-by: Ben Konyi <bkonyi@google.com> Commit-Queue: Daco Harkes <dacoharkes@google.com>
diff --git a/pkg/dartdev/lib/dartdev.dart b/pkg/dartdev/lib/dartdev.dart
@@ -116,11 +116,17 @@ class DartdevRunner extends CommandRunner<int> {
     addCommand(DevToolsCommand(verbose: verbose));
     addCommand(DocCommand(verbose: verbose));
     addCommand(FixCommand(verbose: verbose));
-    addCommand(FormatCommand(verbose: verbose, category: 'Source code'));
+    addCommand(FormatCommand(
+      verbose: verbose,
+      category: CommandCategory.sourceCode.name,
+    ));
     addCommand(InfoCommand(verbose: verbose));
     addCommand(LanguageServerCommand(verbose: verbose));
     addCommand(DartMCPServerCommand(verbose: verbose));
-    addCommand(pubCommand(isVerbose: () => verbose, category: 'Project'));
+    addCommand(pubCommand(
+      isVerbose: () => verbose,
+      category: CommandCategory.project.name,
+    ));
     addCommand(RunCommand(
       verbose: verbose,
       nativeAssetsExperimentEnabled: nativeAssetsExperimentEnabled,
diff --git a/pkg/dartdev/lib/src/commands/analyze.dart b/pkg/dartdev/lib/src/commands/analyze.dart
@@ -100,7 +100,7 @@ class AnalyzeCommand extends DartdevCommand {
   }
 
   @override
-  String get category => 'Source code';
+  CommandCategory get commandCategory => CommandCategory.sourceCode;
 
   @override
   String get invocation => '${super.invocation} [<directory>]';
diff --git a/pkg/dartdev/lib/src/commands/build.dart b/pkg/dartdev/lib/src/commands/build.dart
@@ -36,7 +36,7 @@ class BuildCommand extends DartdevCommand {
   }
 
   @override
-  String get category => 'Project';
+  CommandCategory get commandCategory => CommandCategory.project;
 }
 
 /// Subcommand for `dart build cli`.
diff --git a/pkg/dartdev/lib/src/commands/compilation_server.dart b/pkg/dartdev/lib/src/commands/compilation_server.dart
@@ -44,7 +44,7 @@ class CompilationServerCommand extends DartdevCommand {
   }
 
   @override
-  String get category => 'Tools';
+  CommandCategory get commandCategory => CommandCategory.tools;
 }
 
 class CompilationServerStartCommand extends DartdevCommand {
diff --git a/pkg/dartdev/lib/src/commands/compile.dart b/pkg/dartdev/lib/src/commands/compile.dart
@@ -1148,5 +1148,5 @@ class CompileCommand extends DartdevCommand {
   }
 
   @override
-  String get category => 'Project';
+  CommandCategory get commandCategory => CommandCategory.project;
 }
diff --git a/pkg/dartdev/lib/src/commands/create.dart b/pkg/dartdev/lib/src/commands/create.dart
@@ -62,7 +62,7 @@ class CreateCommand extends DartdevCommand {
   String get invocation => '${super.invocation} <directory>';
 
   @override
-  String get category => 'Project';
+  CommandCategory get commandCategory => CommandCategory.project;
 
   @override
   FutureOr<int> run() async {
diff --git a/pkg/dartdev/lib/src/commands/dart_mcp_server.dart b/pkg/dartdev/lib/src/commands/dart_mcp_server.dart
@@ -40,7 +40,7 @@ EXPERIMENTAL: This tool may change dramatically or disappear at any time.''';
   }
 
   @override
-  String get category => 'Tools';
+  CommandCategory get commandCategory => CommandCategory.tools;
 
   @override
   Future<int> run() async {
diff --git a/pkg/dartdev/lib/src/commands/debug_adapter.dart b/pkg/dartdev/lib/src/commands/debug_adapter.dart
@@ -60,7 +60,7 @@ class DebugAdapterCommand extends DartdevCommand {
   }
 
   @override
-  String get category => 'Tools';
+  CommandCategory get commandCategory => CommandCategory.tools;
 
   @override
   FutureOr<int> run() async {
diff --git a/pkg/dartdev/lib/src/commands/development_service.dart b/pkg/dartdev/lib/src/commands/development_service.dart
@@ -31,7 +31,7 @@ class DevelopmentServiceCommand extends DartdevCommand {
   }
 
   @override
-  String get category => 'Tools';
+  CommandCategory get commandCategory => CommandCategory.tools;
 
   @override
   Future<int> run() async {
diff --git a/pkg/dartdev/lib/src/commands/devtools.dart b/pkg/dartdev/lib/src/commands/devtools.dart
@@ -40,7 +40,7 @@ class DevToolsCommand extends DartdevCommand {
   String get name => 'devtools';
 
   @override
-  String get category => 'Tools';
+  CommandCategory get commandCategory => CommandCategory.tools;
 
   @override
   String get description => DevToolsServer.commandDescription;
diff --git a/pkg/dartdev/lib/src/commands/doc.dart b/pkg/dartdev/lib/src/commands/doc.dart
@@ -56,7 +56,7 @@ For additional documentation generation options, see the 'dartdoc_options.yaml'
   }
 
   @override
-  String get category => 'Source code';
+  CommandCategory get commandCategory => CommandCategory.sourceCode;
 
   @override
   String get invocation => '${super.invocation} [<directory>]';
diff --git a/pkg/dartdev/lib/src/commands/fix.dart b/pkg/dartdev/lib/src/commands/fix.dart
@@ -71,7 +71,7 @@ To use the tool, run either ['dart fix --dry-run'] for a preview of the proposed
   }
 
   @override
-  String get category => 'Source code';
+  CommandCategory get commandCategory => CommandCategory.sourceCode;
 
   @override
   String get description {
diff --git a/pkg/dartdev/lib/src/commands/info.dart b/pkg/dartdev/lib/src/commands/info.dart
@@ -19,7 +19,7 @@ class InfoCommand extends DartdevCommand {
       'Show diagnostic information about the installed tooling.';
 
   @override
-  String get category => 'Tools';
+  CommandCategory get commandCategory => CommandCategory.tools;
 
   InfoCommand({bool verbose = false})
       : super(cmdName, cmdDescription, verbose) {
diff --git a/pkg/dartdev/lib/src/commands/language_server.dart b/pkg/dartdev/lib/src/commands/language_server.dart
@@ -16,7 +16,7 @@ class LanguageServerCommand extends DartdevCommand {
   static const String commandName = 'language-server';
 
   @override
-  String get category => 'Tools';
+  CommandCategory get commandCategory => CommandCategory.tools;
 
   static const String commandDescription = '''
 Start Dart's analysis server.
diff --git a/pkg/dartdev/lib/src/commands/run.dart b/pkg/dartdev/lib/src/commands/run.dart
@@ -313,7 +313,7 @@ class RunCommand extends DartdevCommand {
       '${super.invocation} [<dart-file|package-target> [args]]';
 
   @override
-  String get category => 'Project';
+  CommandCategory get commandCategory => CommandCategory.project;
 
   /// Attempts to compile [executable] to a kernel file using the Resident
   /// Frontend Compiler associated with [residentCompilerInfoFile]. If
diff --git a/pkg/dartdev/lib/src/commands/test.dart b/pkg/dartdev/lib/src/commands/test.dart
@@ -33,7 +33,7 @@ class TestCommand extends DartdevCommand {
   }
 
   @override
-  String get category => 'Project';
+  CommandCategory get commandCategory => CommandCategory.project;
 
   @override
   void printUsage() {
diff --git a/pkg/dartdev/lib/src/commands/tooling_daemon.dart b/pkg/dartdev/lib/src/commands/tooling_daemon.dart
@@ -29,7 +29,7 @@ class ToolingDaemonCommand extends DartdevCommand {
   }
 
   @override
-  String get category => 'Tools';
+  CommandCategory get commandCategory => CommandCategory.tools;
 
   @override
   Future<int> run() async {
diff --git a/pkg/dartdev/lib/src/core.dart b/pkg/dartdev/lib/src/core.dart
@@ -52,6 +52,18 @@ abstract class DartdevCommand extends Command<int> {
   @override
   ArgParser get argParser => _argParser ??= createArgParser();
 
+  @override
+  String get category {
+    if (parent != null) {
+      // Subcommands should not have a top level command category.
+      assert(commandCategory == null);
+      return '';
+    }
+    return commandCategory!.name;
+  }
+
+  CommandCategory? get commandCategory => null;
+
   @override
   String get invocation {
     String result = super.invocation;
@@ -70,6 +82,16 @@ abstract class DartdevCommand extends Command<int> {
       ArgParser(usageLineLength: dartdevUsageLineLength);
 }
 
+enum CommandCategory {
+  project('Project'),
+  sourceCode('Source code'),
+  tools('Tools');
+
+  final String name;
+
+  const CommandCategory(this.name);
+}
+
 extension DartDevCommand<T> on Command<T> {
   /// Return whether commands should emit verbose output.
   bool get verbose => globalResults!.flag('verbose');
diff --git a/pkg/dartdev/test/commands/help_test.dart b/pkg/dartdev/test/commands/help_test.dart
@@ -67,4 +67,40 @@ void help() {
       }
     });
   });
+
+  test('command categories', () async {
+    p = project();
+    final result = await p.run(['help', '--verbose']);
+    // Include the `Available commands:` with the empty line to ensure all
+    // commands have a category.
+    expect(
+        result.stdout,
+        contains(
+          '''
+Available commands:
+
+Project
+  build                 Build a Dart application including native assets.
+  compile               Compile Dart to various formats.
+  create                Create a new Dart project.
+  pub                   Work with packages.
+  run                   Run a Dart program.
+  test                  Run tests for a project.
+
+Source code
+  analyze               Analyze Dart code in a directory.
+  doc                   Generate API documentation for Dart projects.
+  fix                   Apply automated fixes to Dart source code.
+  format                Idiomatically format Dart source code.
+
+Tools
+  compilation-server    Control resident frontend compilers.
+  development-service   Start Dart's development service.
+  devtools              Open DevTools (optionally connecting to an existing application).
+  info                  Show diagnostic information about the installed tooling.
+  language-server       Start Dart's analysis server.
+  tooling-daemon        Start Dart's tooling daemon.
+''',
+        ));
+  });
 }

Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,7 @@ class AnalyzeCommand extends DartdevCommand {`
`100`	`100`	`}`
`101`	`101`
`102`	`102`	`@override`
`103`		`- String get category => 'Source code';`
	`103`	`+ CommandCategory get commandCategory => CommandCategory.sourceCode;`
`104`	`104`
`105`	`105`	`@override`
`106`	`106`	`String get invocation => '${super.invocation} [<directory>]';`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ class BuildCommand extends DartdevCommand {`
`36`	`36`	`}`
`37`	`37`
`38`	`38`	`@override`
`39`		`- String get category => 'Project';`
	`39`	`+ CommandCategory get commandCategory => CommandCategory.project;`
`40`	`40`	`}`
`41`	`41`
`42`	`42`	/// Subcommand for `dart build cli`.
Original file line number	Diff line number	Diff line change
`@@ -44,7 +44,7 @@ class CompilationServerCommand extends DartdevCommand {`
`44`	`44`	`}`
`45`	`45`
`46`	`46`	`@override`
`47`		`- String get category => 'Tools';`
	`47`	`+ CommandCategory get commandCategory => CommandCategory.tools;`
`48`	`48`	`}`
`49`	`49`
`50`	`50`	`class CompilationServerStartCommand extends DartdevCommand {`
Original file line number	Diff line number	Diff line change
`@@ -1148,5 +1148,5 @@ class CompileCommand extends DartdevCommand {`
`1148`	`1148`	`}`
`1149`	`1149`
`1150`	`1150`	`@override`
`1151`		`- String get category => 'Project';`
	`1151`	`+ CommandCategory get commandCategory => CommandCategory.project;`
`1152`	`1152`	`}`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@ EXPERIMENTAL: This tool may change dramatically or disappear at any time.''';`
`40`	`40`	`}`
`41`	`41`
`42`	`42`	`@override`
`43`		`- String get category => 'Tools';`
	`43`	`+ CommandCategory get commandCategory => CommandCategory.tools;`
`44`	`44`
`45`	`45`	`@override`
`46`	`46`	`Future<int> run() async {`
Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@ class DebugAdapterCommand extends DartdevCommand {`
`60`	`60`	`}`
`61`	`61`
`62`	`62`	`@override`
`63`		`- String get category => 'Tools';`
	`63`	`+ CommandCategory get commandCategory => CommandCategory.tools;`
`64`	`64`
`65`	`65`	`@override`
`66`	`66`	`FutureOr<int> run() async {`
Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ class DevelopmentServiceCommand extends DartdevCommand {`
`31`	`31`	`}`
`32`	`32`
`33`	`33`	`@override`
`34`		`- String get category => 'Tools';`
	`34`	`+ CommandCategory get commandCategory => CommandCategory.tools;`
`35`	`35`
`36`	`36`	`@override`
`37`	`37`	`Future<int> run() async {`