Alternate macro api proposal, less visible phases (#1964)

In this proposal, there are no explicit classes you implement for each phase, there is only a single class to implement based on the type of declaration you will annotate.

Each of these classes has a single visit method which gets a declaration argument and a context argument. The context has methods like `buildTypes`, `buildDeclarations`, and `buildDefinition`. These take a callback as an argument, and the callback receives the corresponding builder. It won't be executed until in the right phase.

Some advantages of this api are:

- Can have some shared state between phases, managed by local variables in the `visit` method.
- Less complicated class  heirarchy - far fewer classes to understand.
- The phases are less directly exposed, you don't really have to understand them so much any more.

Some disadvantages of this api are:

- Can result in runtime errors if violating phases - you can't call the `buildTypes` method from within the callback passed to `buildDeclarations` for instance. That would violate ordering, and we would have to throw at runtime. We could lint for this though.
- People may try to share state that isn't shareable across phases (for instance store the TypeBuilder and use it in the declaration phase).
- If only implementing one phase there is more boilerplate.

Author: jakemac53

working/macros/api/builders.dart

@@ -0,0 +1,202 @@
+import 'dart:async';
+
+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 {
+  /// Used to construct a [TypeAnnotation] to a runtime type available to the
+  /// the macro implementation code.
+  ///
+  /// This can be used to emit a reference to it in generated code, or do
+  /// subtype checks (depending on support in the current phase).
+  TypeAnnotation typeAnnotationOf<T>();
+}
+
+/// The api used by [Macro]s to contribute new type declarations to the
+/// current library, and get [TypeAnnotation]s from runtime [Type] objects.
+abstract class TypeBuilder implements Builder {
+  /// Adds a new type declaration to the surrounding library.
+  void declareType(DeclarationCode typeDeclaration);
+}
+
+/// The api used by [Macro]s to contribute new (non-type)
+/// declarations to the current library.
+///
+/// Can also be used to do subtype checks on types.
+abstract class DeclarationBuilder implements Builder {
+  /// Adds a new regular declaration to the surrounding library.
+  ///
+  /// Note that type declarations are not supported.
+  Declaration declareInLibrary(DeclarationCode declaration);
+
+  /// Returns true if [leftType] is a subtype of [rightType].
+  bool isSubtypeOf(TypeAnnotation leftType, TypeAnnotation rightType);
+
+  /// Retruns true if [leftType] is an identical type to [rightType].
+  bool isExactly(TypeAnnotation leftType, TypeAnnotation rightType);
+}
+
+/// The api used by [Macro]s to contribute new members to a class.
+abstract class ClassMemberDeclarationBuilder implements DeclarationBuilder {
+  /// Adds a new declaration to the surrounding class.
+  void declareInClass(DeclarationCode declaration);
+}
+
+/// The api used to introspect on a [ClassDeclaration].
+abstract class ClassIntrospector {
+  /// The fields available for [clazz].
+  ///
+  /// This may be incomplete if in the declaration phase and additional macros
+  /// are going to run on this class.
+  Future<List<FieldDeclaration>> fieldsOf(ClassDeclaration clazz);
+
+  /// The methods available so far for the current class.
+  ///
+  /// This may be incomplete if additional declaration macros are running on
+  /// this class.
+  Future<List<MethodDeclaration>> methodsOf(ClassDeclaration clazz);
+
+  /// The constructors available so far for the current class.
+  ///
+  /// This may be incomplete if additional declaration macros are running on
+  /// this class.
+  Future<List<ConstructorDeclaration>> constructorsOf(ClassDeclaration clazz);
+
+  /// The class that is directly extended via an `extends` clause.
+  Future<ClassDeclaration?> superclassOf(ClassDeclaration clazz);
+
+  /// All of the classes that are mixed in with `with` clauses.
+  Future<List<ClassDeclaration>> mixinsOf(ClassDeclaration clazz);
+}
+
+/// The api used by [Macro]s to reflect on the currently available
+/// members, superclass, and mixins for a given [ClassDeclaration]
+abstract class ClassDeclarationBuilder
+    implements ClassMemberDeclarationBuilder, ClassIntrospector {}
+
+/// The api used by [Macro] to get a [TypeDeclaration] for any given
+/// [TypeAnnotation].
+abstract class TypeIntrospector {
+  /// TODO: Figure out how to deal with `FutureOr<T>`, function types, and
+  /// other non-nominal types.
+  Future<TypeDeclaration> resolve(TypeAnnotation annotation);
+}
+
+/// The base class for builders in the definition phase. These can convert
+/// any [TypeAnnotation] into its corresponding [TypeDeclaration], and also
+/// reflect more deeply on those.
+abstract class DefinitionBuilder
+    implements Builder, ClassIntrospector, TypeIntrospector {}
+
+/// 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].
+  ///
+  /// Throws an [ArgumentError] if there is no field by that name.
+  Future<void> buildField(String name,
+      FutureOr<void> Function(FieldDefinitionBuilder builder) callback);
+
+  /// 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);
+
+  /// 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);
+}
+
+/// The apis used by [Macro]s to define the body of a constructor
+/// or wrap the body of an existing constructor with additional statements.
+abstract class ConstructorDefinitionBuilder implements DefinitionBuilder {
+  /// Augments an existing constructor body with [body].
+  ///
+  /// TODO: Link the library augmentations proposal to describe the semantics.
+  void augment({FunctionBodyCode? body, List<Code>? initializers});
+}
+
+/// The apis used by [Macro]s to augment functions or methods.
+abstract class FunctionDefinitionBuilder implements DefinitionBuilder {
+  /// Augments the function.
+  ///
+  /// TODO: Link the library augmentations proposal to describe the semantics.
+  void augment(FunctionBodyCode body);
+}
+
+/// The api used by [Macro]s to augment a field.
+abstract class FieldDefinitionBuilder implements DefinitionBuilder {
+  /// Augments the field.
+  ///
+  /// TODO: Link the library augmentations proposal to describe the semantics.
+  void augment({
+    DeclarationCode? getter,
+    DeclarationCode? setter,
+    ExpressionCode? initializer,
+  });
+}

working/macros/api/code.dart

@@ -0,0 +1,123 @@
+/// A scope in which to resolve a chunk of code.
+///
+/// TODO: Specify more what these mean, what fields are available (if any), etc.
+abstract class Scope {}
+
+/// The base class representing an arbitrary chunk of Dart code, which may or
+/// may not be syntactically or semantically valid yet.
+class Code {
+  /// The scope in which to resolve anything from [parts] that does not have its
+  /// own scope already defined.
+  final Scope? scope;
+
+  /// All the chunks of [Code] or raw [String]s that comprise this [Code]
+  /// object.
+  final List<Object> parts;
+
+  Code.fromString(String code, {this.scope}) : parts = [code];
+
+  Code.fromParts(this.parts, {this.scope});
+}
+
+/// A piece of code representing a syntactically valid declaration.
+class DeclarationCode extends Code {
+  DeclarationCode.fromString(String code, {Scope? scope})
+      : super.fromString(code, scope: scope);
+
+  DeclarationCode.fromParts(List<Object> parts, {Scope? scope})
+      : super.fromParts(parts, scope: scope);
+}
+
+/// A piece of code representing a syntactically valid element.
+///
+/// Should not include any trailing commas,
+class ElementCode extends Code {
+  ElementCode.fromString(String code, {Scope? scope})
+      : super.fromString(code, scope: scope);
+
+  ElementCode.fromParts(List<Object> parts, {Scope? scope})
+      : super.fromParts(parts, scope: scope);
+}
+
+/// A piece of code representing a syntactically valid expression.
+class ExpressionCode extends Code {
+  ExpressionCode.fromString(String code, {Scope? scope})
+      : super.fromString(code, scope: scope);
+
+  ExpressionCode.fromParts(List<Object> parts, {Scope? scope})
+      : super.fromParts(parts, scope: scope);
+}
+
+/// A piece of code representing a syntactically valid function body.
+///
+/// This includes any and all code after the parameter list of a function,
+/// including modifiers like `async`.
+///
+/// Both arrow and block function bodies are allowed.
+class FunctionBodyCode extends Code {
+  FunctionBodyCode.fromString(String code, {Scope? scope})
+      : super.fromString(code, scope: scope);
+
+  FunctionBodyCode.fromParts(List<Object> parts, {Scope? scope})
+      : super.fromParts(parts, scope: scope);
+}
+
+/// A piece of code representing a syntactically valid identifier.
+class IdentifierCode extends Code {
+  IdentifierCode.fromString(String code, {Scope? scope})
+      : super.fromString(code, scope: scope);
+
+  IdentifierCode.fromParts(List<Object> parts, {Scope? scope})
+      : super.fromParts(parts, scope: scope);
+}
+
+/// A piece of code identifying a named argument.
+///
+/// This should not include any trailing commas.
+class NamedArgumentCode extends Code {
+  NamedArgumentCode.fromString(String code, {Scope? scope})
+      : super.fromString(code, scope: scope);
+
+  NamedArgumentCode.fromParts(List<Object> parts, {Scope? scope})
+      : super.fromParts(parts, scope: scope);
+}
+
+/// A piece of code identifying a syntactically valid function parameter.
+///
+/// This should not include any trailing commas, but may include modifiers
+/// such as `required`, and default values.
+///
+/// There is no distinction here made between named and positional parameters,
+/// nor between optional or required parameters. It is the job of the user to
+/// construct and combine these together in a way that creates valid parameter
+/// lists.
+class ParameterCode extends Code {
+  ParameterCode.fromString(String code, {Scope? scope})
+      : super.fromString(code, scope: scope);
+
+  ParameterCode.fromParts(List<Object> parts, {Scope? scope})
+      : super.fromParts(parts, scope: scope);
+}
+
+/// A piece of code representing a syntactically valid statement.
+///
+/// Should always end with a semicolon.
+class StatementCode extends Code {
+  StatementCode.fromString(String code, {Scope? scope})
+      : super.fromString(code, scope: scope);
+
+  StatementCode.fromParts(List<Object> parts, {Scope? scope})
+      : super.fromParts(parts, scope: scope);
+}
+
+extension Join<T extends Code> on List<T> {
+  /// Joins all the items in [this] with [separator], and returns
+  /// a new list.
+  List<Code> joinAsCode(String separator) => [
+        for (var i = 0; i < length - 1; i++) ...[
+          this[i],
+          Code.fromString(separator),
+        ],
+        last,
+      ];
+}