feat: add BaseClass and Initializer annotations

Author: mcquenji

lib/grumpy_annotations.dart

@@ -1 +1,3 @@
 export 'src/must_call_in_constructor.dart';
+export 'src/base_class.dart';
+export 'src/initializer.dart';

lib/src/base_class.dart

@@ -0,0 +1,43 @@
+import 'package:meta/meta.dart';
+import 'package:meta/meta_meta.dart';
+
+/// {@template layer_class}
+/// Marks a class as a base class.
+///
+/// Subclasses of this class have to follow the following rules:
+/// - They are only allowed to be defined in the layers specified in [allowedLayers].
+/// - They must have the name of the base class as a suffix.
+/// - The file must be in a subdirectory named after the base class in plural snake_case ([typeDirectory]).
+/// - The file the class is defined in must have the same name as the class in snake_case.
+/// - The file must not contain any other classes (except for extensions or mixins).
+/// - Classes defined in the [typeDirectory] must extend this base class.
+///
+/// Unit tests are exempt from these rules.
+/// {@endtemplate}
+@Target({.classType})
+@immutable
+class BaseClass {
+  /// The layers in which subclasses are allowed to be defined.
+  final Set<LayerType> allowedLayers;
+
+  /// The directory name where subclasses must be defined.
+  ///
+  /// If not provided, it is inferred from the class name
+  /// by converting it to plural snake_case.
+  final String? typeDirectory;
+
+  /// If true, subclasses must have the name of the base class as a suffix.
+  final bool forceSuffix;
+
+  /// {@macro layer_class}
+  const BaseClass({
+    this.allowedLayers = const {.domain, .infra, .presentation},
+    this.typeDirectory,
+    this.forceSuffix = true,
+  });
+}
+
+enum LayerType { infra, domain, presentation }
+
+/// {@macro layer_class}
+const base = BaseClass();

lib/src/initializer.dart

@@ -0,0 +1,56 @@
+import 'package:meta/meta.dart';
+import 'package:meta/meta_meta.dart';
+import 'package:grumpy_annotations/grumpy_annotations.dart';
+
+/// {@template initializer}
+/// Marks a method as the *initialization entrypoint* of a class.
+///
+/// This annotation is meant for frameworks or patterns where the constructor
+/// is not the right place to run setup logic (e.g. Flutter `State.initState`).
+///
+/// If a class declares a method annotated with `@initializer`, then that method
+/// becomes the place where all [MustCallInConstructor]-annotated methods must
+/// be invoked.
+///
+/// In other words:
+///
+/// - **With an initializer:** required calls move from the constructor to the
+///   `@initializer` method.
+/// - **Without an initializer:** required calls must still happen in the
+///   constructor (default behavior of [MustCallInConstructor]).
+///
+/// The “called anywhere in the inheritance chain satisfies subclasses” rule
+/// still applies: if a superclass initializer performs the required calls,
+/// subclasses do not need to repeat them.
+///
+/// Example usage in a Flutter `State` class:
+/// ```dart
+/// class MyWidgetState extends State<MyWidget> with SomeMixin {
+///   @override
+///   @initializer
+///   void initState() {
+///     super.initState();
+///
+///     someMixinSetup(); // This method is annotated with [MustCallInConstructor] in SomeMixin
+///   }
+/// }
+/// ```
+///
+/// Flutter `State` objects often require setup in `initState()` rather than
+/// constructors. Annotate `initState()` with `@initializer`, and annotate the
+/// required setup hooks with [MustCallInConstructor] to enforce they are
+/// invoked from `initState()`.
+///
+/// See also:
+///   - [MustCallInConstructor] for marking required setup methods.
+///
+/// {@endtemplate}
+@immutable
+@Target({TargetKind.method})
+class Initializer {
+  /// {@macro initializer}
+  const Initializer();
+}
+
+/// {@macro initializer}
+const initializer = Initializer();

lib/src/must_call_in_constructor.dart

@@ -1,5 +1,6 @@
 import 'package:meta/meta.dart';
 import 'package:meta/meta_meta.dart';
+import 'package:grumpy_annotations/grumpy_annotations.dart';
 
 /// {@template hook_installer}
 /// An annotation indicating that the annotated method
@@ -14,6 +15,9 @@ import 'package:meta/meta_meta.dart';
 /// Note: If any class in the inheritance chain calls the
 /// annotated method in its constructor, the requirement
 /// is considered satisfied for subclasses.
+///
+/// See also:
+///   - [Initializer] for marking alternative initialization entrypoints.
 /// {@endtemplate}
 @Target({TargetKind.method})
 @immutable
@@ -25,14 +29,16 @@ class MustCallInConstructor {
   final bool concreteOnly;
 
   /// A list of types that are exempt from this requirement.
+  ///
   /// If the class using the mixin is a subtype of any of these types,
-  /// the requirement is considered satisfied.
-  final List<Type> exceptions;
+  /// the requirement is considered satisfied,
+  /// and the method **must not** be called in the constructor.
+  final List<Type> exempt;
 
   /// {@macro hook_installer}
   const MustCallInConstructor({
     this.concreteOnly = true,
-    this.exceptions = const [],
+    this.exempt = const [],
   });
 }
 

pubspec.yaml

@@ -4,7 +4,7 @@ version: 1.0.0
 # repository: https://github.com/my_org/my_repo
 
 environment:
-  sdk: ^3.9.2
+  sdk: ^3.10.0
 
 # Add regular dependencies here.
 dependencies: