Revert back to original macro api style (#1986)

Opening for discussion.

This PR moves us back towards the original proposal, where there is a different type to implement for each phase, and each declaration type you can run on.

**Advantages**:

- It is easier for an implementation to know up front exactly which phases a given macro will run in.
- It allows an implementation to do more efficient invalidation safely - since macros can't share state across phases with local variables you are free to run only a specific phase of a given macro.
- Macros are more composable - you have per-phase functions you can directly delegate work to, instead of only a more general function.
- We don't have to worry about  users trying to share objects they shouldn't through local variables (`TypeBuilders` etc).
- Less nesting, avoids the "callback" style which can be a bit messy.

**Disadvantages**:

- You have to delegate each phase explicitly for any macro you are composing with (see changes to the example).
- There is a disconnect between where you declare something and where you define it.

I also added the missing `VariableDefinition` and `VariableDefinitionBuilder` classes for introspecting/augmenting top level variables.

Author: jakemac53

working/macros/api/builders.dart

@@ -4,65 +4,6 @@ import 'code.dart';
 import 'introspection.dart';
 import 'macros.dart'; // For dart docs.
 
-/// The interface used by [Macro]s to modify the current library.
-abstract class LibraryContext {
-  /// Used to contribute new type declarations to this library.
-  void buildTypes(FutureOr<void> Function(TypeBuilder) callback);
-
-  /// Used to contribute new non-type declarations to this library.
-  void buildDeclarations(FutureOr<void> Function(DeclarationBuilder) callback);
-}
-
-/// The interface used by [FunctionMacro]s to modify the function.
-abstract class FunctionContext implements LibraryContext {
-  /// Used to augment a function definition.
-  void buildDefinition(
-      FutureOr<void> Function(FunctionDefinitionBuilder) callback);
-}
-
-/// The interface used by [ClassMacro]s to modify the class.
-abstract class ClassContext implements LibraryContext {
-  /// Used to contribute new non-type declarations to this library or class.
-  @override
-  void buildDeclarations(
-      FutureOr<void> Function(ClassDeclarationBuilder) callback);
-
-  /// Used to augment any members in this class.
-  void buildDefinitions(
-      FutureOr<void> Function(ClassDefinitionBuilder) callback);
-}
-
-/// The interface used by all [Macro]s that run on a member of a class, to add
-/// declarations to that class or the surrounding library.
-abstract class ClassMemberContext implements LibraryContext {
-  /// Used to contribute new non-type declarations to the surrounding library
-  /// or class.
-  @override
-  void buildDeclarations(
-      FutureOr<void> Function(ClassMemberDeclarationBuilder) callback);
-}
-
-/// The interface used by [FieldMacro]s to modify the field.
-abstract class FieldContext implements ClassMemberContext {
-  /// Used to augment a field definition.
-  void buildDefinition(
-      FutureOr<void> Function(FieldDefinitionBuilder) callback);
-}
-
-/// The interface used by [MethodMacro]s to modify the method.
-abstract class MethodContext implements ClassMemberContext {
-  /// Used to augment a method definition.
-  void buildDefinition(
-      FutureOr<void> Function(FunctionDefinitionBuilder) callback);
-}
-
-/// The interface used by [ConstructorMacro]s to modify the constructor.
-abstract class ConstructorContext implements ClassMemberContext {
-  /// Used to augment a constructor definition.
-  void buildDefinition(
-      FutureOr<void> Function(ConstructorDefinitionBuilder) callback);
-}
-
 /// The base interface used to add declarations to the program as well
 /// as augment existing ones.
 abstract class Builder {
@@ -153,23 +94,20 @@ abstract class DefinitionBuilder
 /// The apis used by [Macro]s that run on classes, to fill in the definitions
 /// of any external declarations within that class.
 abstract class ClassDefinitionBuilder implements DefinitionBuilder {
-  /// Retrieve a [FieldDefinitionBuilder] for a field by [name].
+  /// Retrieve a [VariableDefinitionBuilder] for a field by [name].
   ///
   /// Throws an [ArgumentError] if there is no field by that name.
-  Future<void> buildField(String name,
-      FutureOr<void> Function(FieldDefinitionBuilder builder) callback);
+  VariableDefinitionBuilder buildField(String name);
 
   /// Retrieve a [FunctionDefinitionBuilder] for a method by [name].
   ///
   /// Throws an [ArgumentError] if there is no method by that name.
-  Future<void> buildMethod(String name,
-      FutureOr<void> Function(FunctionDefinitionBuilder builder) callback);
+  FunctionDefinitionBuilder buildMethod(String name);
 
   /// Retrieve a [ConstructorDefinitionBuilder] for a constructor by [name].
   ///
   /// Throws an [ArgumentError] if there is no constructor by that name.
-  Future<void> buildConstructor(String name,
-      FutureOr<void> Function(ConstructorDefinitionBuilder builder) callback);
+  ConstructorDefinitionBuilder buildConstructor(String name);
 }
 
 /// The apis used by [Macro]s to define the body of a constructor
@@ -189,8 +127,8 @@ abstract class FunctionDefinitionBuilder implements DefinitionBuilder {
   void augment(FunctionBodyCode body);
 }
 
-/// The api used by [Macro]s to augment a field.
-abstract class FieldDefinitionBuilder implements DefinitionBuilder {
+/// The api used by [Macro]s to augment a top level variable or instance field.
+abstract class VariableDefinitionBuilder implements DefinitionBuilder {
   /// Augments the field.
   ///
   /// TODO: Link the library augmentations proposal to describe the semantics.

working/macros/api/introspection.dart

@@ -106,24 +106,27 @@ abstract class ConstructorDeclaration implements MethodDeclaration {
   bool get isFactory;
 }
 
-/// Field introspection information ..
-abstract class FieldDeclaration implements Declaration {
+/// Variable introspection information.
+abstract class VariableDeclaration implements Declaration {
   /// Whether this function has an `abstract` modifier.
   bool get isAbstract;
 
   /// Whether this function has an `external` modifier.
   bool get isExternal;
 
-  /// Type type of this field.
+  /// The type of this field.
   TypeAnnotation get type;
 
-  /// The class that defines this method.
-  TypeAnnotation get definingClass;
-
   /// A [Code] object representing the initializer for this field, if present.
   Code? get initializer;
 }
 
+/// Field introspection information ..
+abstract class FieldDeclaration implements VariableDeclaration {
+  /// The class that defines this method.
+  TypeAnnotation get definingClass;
+}
+
 /// Parameter introspection information.
 abstract class ParameterDeclaration {
   /// The name of the parameter.

working/macros/api/macros.dart

@@ -7,34 +7,132 @@ import 'introspection.dart';
 abstract class Macro {}
 
 /// The interface for [Macro]s that can be applied to any top level function,
-/// instance method, or static method.
-abstract class FunctionMacro implements Macro {
-  /// Invoked for any function that is annotated with this macro.
-  FutureOr<void> visitFunction(
-      FunctionDeclaration function, FunctionContext context);
+/// instance method, or static method, and wants to contribute new type
+/// declarations to the program.
+abstract class FunctionTypesMacro implements Macro {
+  FutureOr<void> buildTypesForFunction(
+      FunctionDeclaration function, TypeBuilder builder);
 }
 
-/// The interface for [Macro]s that can be applied to classes.
-abstract class ClassMacro implements Macro {
-  /// Invoked for any class that is annotated with this macro.
-  FutureOr<void> visitClass(ClassDeclaration clazz, ClassContext context);
+/// The interface for [Macro]s that can be applied to any top level function,
+/// instance method, or static method, and wants to contribute new non-type
+/// declarations to the program.
+abstract class FunctionDeclarationsMacro implements Macro {
+  FutureOr<void> buildDeclarationsForFunction(
+      FunctionDeclaration function, DeclarationBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any top level function,
+/// instance method, or static method, and wants to augment the function
+/// definition.
+abstract class FunctionDefinitionMacro implements Macro {
+  FutureOr<void> buildDefinitionForFunction(
+      FunctionDeclaration function, FunctionDefinitionBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any top level variable or
+/// instance field, and wants to contribute new type declarations to the
+/// program.
+abstract class VariableTypesMacro implements Macro {
+  FutureOr<void> buildTypesForVariable(
+      VariableDeclaration variable, TypeBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any top level variable or
+/// instance field and wants to contribute new non-type declarations to the
+/// program.
+abstract class VariableDeclarationsMacro implements Macro {
+  FutureOr<void> buildDeclarationsForVariable(
+      VariableDeclaration variable, DeclarationBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any top level variable
+/// or instance field, and wants to augment the variable definition.
+abstract class VariableDefinitionMacro implements Macro {
+  FutureOr<void> buildDefinitionForFunction(
+      VariableDeclaration variable, VariableDefinitionBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any class, and wants to
+/// contribute new type declarations to the program.
+abstract class ClassTypesMacro implements Macro {
+  FutureOr<void> buildTypesForClass(
+      ClassDeclaration clazz, TypeBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any class, and wants to
+/// contribute new non-type declarations to the program.
+abstract class ClassDeclarationsMacro implements Macro {
+  FutureOr<void> buildDeclarationsForClass(
+      ClassDeclaration clazz, ClassDeclarationBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any class, and wants to
+/// augment the definitions of members on the class.
+abstract class ClassDefinitionMacro implements Macro {
+  FutureOr<void> buildDefinitionForClass(
+      ClassDeclaration clazz, ClassDefinitionBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any field, and wants to
+/// contribute new type declarations to the program.
+abstract class FieldTypesMacro implements Macro {
+  FutureOr<void> buildTypesForField(
+      FieldDeclaration field, TypeBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any field, and wants to
+/// contribute new type declarations to the program.
+abstract class FieldDeclarationsMacro implements Macro {
+  FutureOr<void> buildTypesForField(
+      FieldDeclaration field, ClassMemberDeclarationBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any field, and wants to
+/// augement the field definition.
+abstract class FieldDefinitionsMacro implements Macro {
+  FutureOr<void> buildDefinitionForField(
+      FieldDeclaration field, VariableDefinitionBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any method, and wants to
+/// contribute new type declarations to the program.
+abstract class MethodTypesMacro implements Macro {
+  FutureOr<void> buildTypesForMethod(
+      MethodDeclaration method, TypeBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any method, and wants to
+/// contribute new non-type declarations to the program.
+abstract class MethodDeclarationDeclarationsMacro implements Macro {
+  FutureOr<void> buildDeclarationsForMethod(
+      MethodDeclaration method, ClassMemberDeclarationBuilder builder);
+}
+
+/// The interface for [Macro]s that can be applied to any method, and wants to
+/// augment the function definition.
+abstract class MethodDefinitionMacro implements Macro {
+  FutureOr<void> buildDefinitionForMethod(
+      MethodDeclaration method, FunctionDefinitionBuilder builder);
 }
 
-/// The interface for [Macro]s that can be applied to fields.
-abstract class FieldMacro implements Macro {
-  /// Invoked for any field that is annotated with this macro
-  FutureOr<void> visitField(FieldDeclaration field, FieldContext context);
+/// The interface for [Macro]s that can be applied to any constructor, and wants
+/// to contribute new type declarations to the program.
+abstract class ConstructorTypesMacro implements Macro {
+  FutureOr<void> buildTypesForConstructor(
+      ConstructorDeclaration method, TypeBuilder builder);
 }
 
-/// The interface for [Macro]s that can be applied to methods.
-abstract class MethodMacro implements Macro {
-  /// Invoked for any method that is annotated with this macro.
-  FutureOr<void> visitMethod(MethodDeclaration method, MethodContext context);
+/// The interface for [Macro]s that can be applied to any constructors, and
+/// wants to contribute new non-type declarations to the program.
+abstract class ConstructorDeclarationDeclarationsMacro implements Macro {
+  FutureOr<void> buildDeclarationsForConstructor(
+      ConstructorDeclaration method, ClassMemberDeclarationBuilder builder);
 }
 
-/// The interface for [Macro]s that can be applied to constructors.
-abstract class ConstructorMacro implements Macro {
-  /// Invoked for each constructor annotated with this macro.
-  FutureOr<void> visitConstructor(
-      ConstructorDeclaration constructor, ConstructorContext context);
+/// The interface for [Macro]s that can be applied to any constructor, and wants
+/// to augment the function definition.
+abstract class ConstructorDefinitionMacro implements Macro {
+  FutureOr<void> buildDefinitionForConstructor(
+      ConstructorDeclaration method, ConstructorDefinitionBuilder builder);
 }