Tests/goldens

README.md

@@ -84,16 +84,15 @@ environment:
   sdk: ^3.0.0
 
 dependencies:
-  cli_annotations: ^0.1.0-dev.1
+  cli_annotations: ^0.1.0-dev.4
 
 dev_dependencies:
- build_runner: ^2.4.8
-  cli_gen: ^0.1.0-dev.1
+  build_runner: ^2.4.8
+  cli_gen: ^0.1.0-dev.4
 
 # define an executable name (optional)
 executables:
-  dart_git:
-    path: main # file name of `main()` in bin/ directory
+  dart_git: main
 ```
 
 You can optionally define an executable name and activate it using [pub global activate](https://dart.dev/tools/pub/cmd/pub-global#activating-a-package-on-your-local-machine).
@@ -121,7 +120,7 @@ class GitRunner extends _$GitRunner {
 
 ### Define a Command
 
-Create a `Command` by simply creating a method on the class; any type can be used as a parameter.
+Inside the `CommandRunner` class, create a `Command` by creating a method and annotating it with `@cliCommand`. See the [Features](#features) section for more information on the supported types and features.
 
 ```dart
 @cliRunner
@@ -137,14 +136,35 @@ class GitRunner extends _$GitRunner {
 }
 ```
 
+You can create as many commands inside the `CommandRunner` class as you'd like:
+
+```dart
+@cliRunner
+class GitRunner extends _$GitRunner {
+  @cliCommand
+  Future<void> merge({
+    required String branch,
+    MergeStrategy strategy = MergeStrategy.ort,
+    bool? commit,
+  }) async { /* ... */ }
+
+  @cliCommand
+  Future<void> stashPush() async { /* ... */ }
+
+  @cliCommand
+  Future<void> stashPop() async { /* ... */ }
+
+  // ...
+}
+```
+
 ### Define a Subcommand
 
 As your application grows, you may want to separate your commands into their own groups.
 
-You can create a `Subcommand` by annotating a class with `@cliSubcommand` and extending the generated superclass.
+To do so, create a `Subcommand` class by annotating the class with `@cliSubcommand` and extending the generated superclass.
 
 ```dart
-// Create your subcommand
 @cliSubcommand
 class StashSubcommand extends _$StashSubcommand {
   @cliCommand
@@ -154,11 +174,15 @@ class StashSubcommand extends _$StashSubcommand {
   Future<void> pop() async { /* ... */ }
 }
 
-// Then mount it to your `CommandRunner` or a parent `Subcommand`
+```
+
+Subcommands can then be connected to the main `CommandRunner` class, or to another `Subcommand` class, by using the `@cliMount` annotation.
+
+```dart
 @cliRunner
 class GitRunner extends _$GitRunner {
-  @mount
-  Command get stash => StashSubcommand();
+  @cliMount
+  StashSubcommand get stash => StashSubcommand();
 }
 ```
 

docs/pub_example/pubspec.lock

@@ -119,14 +119,14 @@ packages:
       path: "../../src/cli_annotations"
       relative: true
     source: path
-    version: "0.1.0-dev.3"
+    version: "0.1.0-dev.4"
   cli_gen:
     dependency: "direct dev"
     description:
       path: "../../src/cli_gen"
       relative: true
     source: path
-    version: "0.1.0-dev.3"
+    version: "0.1.0-dev.4"
   code_builder:
     dependency: transitive
     description:

example/analysis_options.yaml

@@ -7,4 +7,4 @@ analyzer:
 linter:
   rules:
     prefer_relative_imports: true
-    prefer_if_null_operators: false
+    # prefer_if_null_operators: false

example/lib/runner.dart

@@ -31,7 +31,6 @@ class GitRunner extends _$GitRunner<void> {
     int? fooWithDefault,
 
     /// Perform the merge and commit the result.
-
     bool? commit,
   }) async {
     print('Merging branch $branch');

example/pubspec.lock

@@ -119,14 +119,14 @@ packages:
       path: "../src/cli_annotations"
       relative: true
     source: path
-    version: "0.1.0-dev.2"
+    version: "0.1.0-dev.4"
   cli_gen:
     dependency: "direct dev"
     description:
       path: "../src/cli_gen"
       relative: true
     source: path
-    version: "0.1.0-dev.2"
+    version: "0.1.0-dev.4"
   code_builder:
     dependency: transitive
     description:

melos.yaml

@@ -7,6 +7,7 @@ packages:
   - src/cli_annotations
   - src/cli_gen
   - src/cli_gen/test/**
+  - test/goldens
 
 scripts:
   analyze:
@@ -23,7 +24,7 @@ scripts:
     exec: dart test
 
     packageFilters:
-      published: true
+      dirExists: test
   build:
     run: dart run build_runner build -d
 

pubspec.yaml

@@ -7,13 +7,13 @@ environment:
 dependencies:
   analyzer: ^6.4.1
   args: ^2.4.2
-  cli_annotations: ^0.1.0-dev.2
+  cli_annotations: ^0.1.0-dev.4
   freezed_annotation: ^2.4.1
   json_annotation: ^4.8.1
 
 dev_dependencies:
   build_runner: ^2.4.8
-  cli_gen: ^0.1.0-dev.2
+  cli_gen: ^0.1.0-dev.4
   freezed: ^2.4.7
   json_serializable: ^6.7.1
   lints: ^3.0.0

src/cli_annotations/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.1.0-dev.5
+
+- feat: Warning on `cliCommand` use on a class, rather than a method/function
+
 ## 0.1.0-dev.4
 
 - feat: Support for adding a generic type to `Command` and `CommandRunner`

src/cli_annotations/lib/src/commands.dart

@@ -26,7 +26,7 @@ import 'package:meta/meta_meta.dart';
 /// }
 /// ```
 /// {@endtemplate}
-@Target({TargetKind.method, TargetKind.function, TargetKind.classType})
+@Target({TargetKind.method, TargetKind.function})
 class CliCommand {
   final String? name;
 

src/cli_gen/lib/src/analysis/parameters/default_value_code_builder.dart

@@ -131,7 +131,7 @@
     }
 
     throw InvalidGenerationSourceError(
-      'Invalid type for constant value: $thisType',
+      'Unknown type for constant value: $thisType',
     );
   }
 

src/cli_gen/lib/src/code/command/command_builder.dart

@@ -36,10 +36,12 @@ class CommandBuilder {
             }),
           );
 
-          const argParserBuilder = ArgParserInstanceExp();
-          builder.body = argParserBuilder
-              .buildArgParserCascadeFromRef(model.parameters)
-              .statement;
+          if (model.parameters.isNotEmpty) {
+            const argParserBuilder = ArgParserInstanceExp();
+            builder.body = argParserBuilder
+                .buildArgParserCascadeFromRef(model.parameters)
+                .statement;
+          }
         }),
       );
 
@@ -52,6 +54,7 @@ class CommandBuilder {
         builder.modifier = FieldModifier.final$;
 
         builder.type = FunctionType((builder) {
+          builder.returnType = model.returnType;
           final requiredPositionalParams =
               model.parameters.where((e) => !e.isNamed && e.isRequired);
           builder.requiredParameters.addAll(
@@ -127,10 +130,11 @@ class CommandBuilder {
 
             builder.statements.addAll([
               // -- declare a `results` variable --
-              declareFinal('results')
-                  .assign(refer('argResults'))
-                  .nullChecked
-                  .statement,
+              if (model.parameters.isNotEmpty)
+                declareFinal('results')
+                    .assign(refer('argResults'))
+                    .nullChecked
+                    .statement,
 
               // -- call the user method --
               userMethodCallBuilder.buildInlineCallStatement(model),

src/cli_gen/lib/src/code/command/runner_builder.dart

@@ -48,6 +48,11 @@ class RunnerBuilder {
         builder.symbol = 'T';
       }));
 
+      builder.docs.addAll([
+        if (model.docComments != null) '/// ${model.docComments}\n///',
+        _classDocComments,
+      ]);
+
       builder.constructors.add(
         Constructor((builder) {
           // -- super initializer --
@@ -60,21 +65,28 @@ class RunnerBuilder {
           );
 
           // -- the constructor body --
-          // adds nested commands and `@mount` subcommands to the CommandRunner
-          final bodyBuilder = SubcommandConstructorBodyBuilder();
-          builder.body = bodyBuilder.buildSubcommandConstructorBody(model);
+          if (model.commandMethods.isNotEmpty ||
+              model.mountedSubcommands.isNotEmpty) {
+            // adds nested commands and `@mount` subcommands to the CommandRunner
+            final bodyBuilder = SubcommandConstructorBodyBuilder();
+            builder.body = bodyBuilder.buildSubcommandConstructorBody(model);
+          }
         }),
       );
 
       // modifies the return type as a nullable, then wraps it in a Future
       final runReturnType = TypeReference((builder) {
         builder.symbol = Identifiers.dart.future.symbol;
         builder.url = Identifiers.dart.future.url;
-        final nestedType = (model.bound ?? Identifiers.dart.dynamic);
+        final nestedType =
+            (model.bound ?? Identifiers.dart.dynamic).toTypeRef();
+        // `void?` and `dynamic?` are not valid, but any other type should be
+        // nullable (according to `args``CommandRunner.run` return type)
+        final isNullable =
+            nestedType.symbol != 'void' && nestedType.symbol != 'dynamic';
+
         builder.types.add(
-          nestedType.toTypeRef(
-            isNullable: nestedType.symbol == 'void' ? null : true,
-          ),
+          nestedType.toTypeRef(isNullable: isNullable),
         );
       });
 
@@ -115,3 +127,10 @@ class RunnerBuilder {
     });
   }
 }
+
+const _classDocComments = '''
+/// A class for invoking [Command]s based on raw command-line arguments.
+///
+/// The type argument `T` represents the type returned by [Command.run] and
+/// [CommandRunner.run]; it can be ommitted if you're not using the return
+/// values.''';

src/cli_gen/lib/src/code/command/subcommand_builder.dart

@@ -19,9 +19,9 @@ class SubcommandBuilder {
     const commandBuilder = CommandBuilder();
     final subcommandClass = buildSubcommandClass(model);
 
-    final subcommands = model.commandMethods.map((e) {
-      return commandBuilder.buildCommandClass(e);
-    });
+    final subcommands = model.commandMethods.map(
+      commandBuilder.buildCommandClass,
+    );
 
     return [subcommandClass, ...subcommands];
   }
@@ -48,12 +48,15 @@ class SubcommandBuilder {
       // -- class constructor --
       builder.constructors.add(
         Constructor((constructor) {
-          constructor.body = Block((block) {
-            final constructorBodyBuilder = SubcommandConstructorBodyBuilder();
-            block.statements.add(
-              constructorBodyBuilder.buildSubcommandConstructorBody(model),
-            );
-          });
+          if (model.commandMethods.isNotEmpty ||
+              model.mountedSubcommands.isNotEmpty) {
+            constructor.body = Block((block) {
+              final constructorBodyBuilder = SubcommandConstructorBodyBuilder();
+              block.statements.add(
+                constructorBodyBuilder.buildSubcommandConstructorBody(model),
+              );
+            });
+          }
         }),
       );