add throwOnUnresolved to TypeChecker methods to allow matching annotations in a non-fully resolved context (#249)

Author: jakemac53

CHANGELOG.md

@@ -14,7 +14,7 @@
     `package:json_serializable`.
   * Removed `lib/builder.dart`. Import through `source_gen.dart` instead.
   * Removed `OutputFormatter` typedef.
-  
+
 * Add `LibraryReader.allElements` - a utility to iterate across all `Element`
   instances contained in Dart library.
 * Add `LibraryReader.element` to get back to the `LibraryElement` instance.
@@ -29,6 +29,12 @@ findTokenField(DartObject o) {
 }
 ```
 
+* Add `throwOnUnresolved` optional parameter to `TypeChecker.annotationsOf`,
+  `TypeChecker.annotationsOfExact`, `TypeChecker.firstAnnotationOf`, and
+  `TypeChecker.firstAnnotationOfExact`. Setting this to `false` will enable you
+  to check for matching annotations with incomplete type information (at your
+  own risk).
+
 ## 0.6.1+1
 
 * Tighten constraint on `source_span`.
@@ -70,14 +76,14 @@ findTokenField(DartObject o) {
   ```dart
   import 'package:analyzer/dart/element/type.dart';
   import 'package:source_gen/source_gen.dart';
-  
+
   void checkType(DartType dartType) {
     // Checks compared to runtime type `SomeClass`.
     print(const TypeChecker.forRuntime(SomeClass).isExactlyType(dartType));
-    
+
     // Checks compared to a known Url/Symbol:
     const TypeChecker.forUrl('package:foo/foo.dart#SomeClass');
-    
+
     // Checks compared to another resolved `DartType`:
     const TypeChecker.forStatic(anotherDartType);
   }
@@ -86,19 +92,19 @@ findTokenField(DartObject o) {
 * Failing to add a `library` directive to a library that is being used as a
   generator target that generates partial files (`part of`) is now an explicit
   error that gives a hint on how to name and fix your library:
-  
+
   ```bash
   > Could not find library identifier so a "part of" cannot be built.
   >
   > Consider adding the following to your source file:
   >
   > "library foo.bar;"
   ```
-  
+
   In Dart SDK `>=1.25.0` this can be relaxed as `part of` can refer to a path.
   To opt-in, `GeneratorBuilder` now has a new flag, `requireLibraryDirective`.
   Set it to `false`, and also set your `sdk` constraint appropriately:
-  
+
   ```yaml
     sdk: '>=1.25.0 <2.0.0'
   ```
@@ -107,11 +113,11 @@ findTokenField(DartObject o) {
   high-level APIs, including `findType`, which traverses `export` directives
   for publicly exported types. For example, to find `Generator` from
   `package:source_gen/source_gen.dart`:
-  
+
   ```dart
   void example(LibraryElement pkgSourceGen) {
     var library = new LibraryReader(pkgSourceGen);
-  
+
     // Instead of pkgSourceGen.getType('Generator'), which is null.
     library.findType('Generator');
   }
@@ -120,26 +126,26 @@ findTokenField(DartObject o) {
 * Added `ConstantReader`, a high-level API for reading from constant (static)
   values from Dart source code (usually represented by `DartObject` from the
   `analyzer` package):
-  
+
   ```dart
   abstract class ConstantReader {
     factory ConstantReader(DartObject object) => ...
-  
+
     // Other methods and properties also exist.
-  
+
     /// Reads[ field] from the constant as another constant value.
     ConstantReader read(String field);
-  
+
     /// Reads [field] from the constant as a boolean.
     ///
     /// If the resulting value is `null`, uses [defaultTo] if defined.
     bool readBool(String field, {bool defaultTo()});
-  
+
     /// Reads [field] from the constant as an int.
     ///
     /// If the resulting value is `null`, uses [defaultTo] if defined.
     int readInt(String field, {int defaultTo()});
-  
+
     /// Reads [field] from the constant as a string.
     ///
     /// If the resulting value is `null`, uses [defaultTo] if defined.

lib/src/type_checker.dart

@@ -55,26 +55,34 @@ abstract class TypeChecker {
   /// Returns the first constant annotating [element] assignable to this type.
   ///
   /// Otherwise returns `null`.
-  DartObject firstAnnotationOf(Element element) {
+  ///
+  /// Throws on unresolved annotations unless [throwOnUnresolved] is `false`.
+  DartObject firstAnnotationOf(Element element, {bool throwOnUnresolved}) {
     if (element.metadata.isEmpty) {
       return null;
     }
-    final results = annotationsOf(element);
+    final results =
+        annotationsOf(element, throwOnUnresolved: throwOnUnresolved);
     return results.isEmpty ? null : results.first;
   }
 
   /// Returns the first constant annotating [element] that is exactly this type.
-  DartObject firstAnnotationOfExact(Element element) {
+  ///
+  /// Throws on unresolved annotations unless [throwOnUnresolved] is `false`.
+  DartObject firstAnnotationOfExact(Element element, {bool throwOnUnresolved}) {
     if (element.metadata.isEmpty) {
       return null;
     }
-    final results = annotationsOfExact(element);
+    final results =
+        annotationsOfExact(element, throwOnUnresolved: throwOnUnresolved);
     return results.isEmpty ? null : results.first;
   }
 
-  DartObject _checkedConstantValue(ElementAnnotation annotation) {
+  DartObject _computeConstantValue(ElementAnnotation annotation,
+      {bool throwOnUnresolved}) {
+    throwOnUnresolved ??= true;
     final result = annotation.computeConstantValue();
-    if (result == null) {
+    if (result == null && throwOnUnresolved) {
       throw new StateError(
           'Could not resolve $annotation. An import or dependency may be '
           'missing or invalid.');
@@ -83,14 +91,24 @@ abstract class TypeChecker {
   }
 
   /// Returns annotating constants on [element] assignable to this type.
-  Iterable<DartObject> annotationsOf(Element element) => element.metadata
-      .map(_checkedConstantValue)
-      .where((a) => a?.type != null && isAssignableFromType(a.type));
+  ///
+  /// Throws on unresolved annotations unless [throwOnUnresolved] is `false`.
+  Iterable<DartObject> annotationsOf(Element element,
+          {bool throwOnUnresolved}) =>
+      element.metadata
+          .map((annotation) => _computeConstantValue(annotation,
+              throwOnUnresolved: throwOnUnresolved))
+          .where((a) => a?.type != null && isAssignableFromType(a.type));
 
   /// Returns annotating constants on [element] of exactly this type.
-  Iterable<DartObject> annotationsOfExact(Element element) => element.metadata
-      .map(_checkedConstantValue)
-      .where((a) => a?.type != null && isExactlyType(a.type));
+  ///
+  /// Throws on unresolved annotations unless [throwOnUnresolved] is `false`.
+  Iterable<DartObject> annotationsOfExact(Element element,
+          {bool throwOnUnresolved}) =>
+      element.metadata
+          .map((annotation) => _computeConstantValue(annotation,
+              throwOnUnresolved: throwOnUnresolved))
+          .where((a) => a?.type != null && isExactlyType(a.type));
 
   /// Returns `true` if the type of [element] can be assigned to this type.
   bool isAssignableFrom(Element element) =>

test/type_checker_test.dart

@@ -286,4 +286,56 @@ void main() {
       expect(bExact.map((a) => a.type.name), ['B']);
     });
   });
+
+  group('unresolved annotations', () {
+    TypeChecker $A;
+    ClassElement $ExampleOfA;
+
+    setUpAll(() async {
+      final resolver = await resolveSource(r'''
+      library _test;
+
+      // Put the missing annotation first so it throws.
+      @B()
+      @A()
+      class ExampleOfA {}
+
+      class A {
+        const A();
+      }
+    ''');
+      final library = resolver.getLibraryByName('_test');
+      $A = new TypeChecker.fromStatic(library.getType('A').type);
+      $ExampleOfA = library.getType('ExampleOfA');
+    });
+
+    test('should throw by default', () {
+      expect(() => $A.firstAnnotationOf($ExampleOfA), throwsStateError);
+      expect(() => $A.annotationsOf($ExampleOfA), throwsStateError);
+      expect(() => $A.firstAnnotationOfExact($ExampleOfA), throwsStateError);
+      expect(() => $A.annotationsOfExact($ExampleOfA), throwsStateError);
+    });
+
+    test('should not throw if `throwOnUnresolved` == false', () {
+      expect(
+          $A.firstAnnotationOf($ExampleOfA, throwOnUnresolved: false).type.name,
+          'A');
+      expect(
+          $A
+              .annotationsOf($ExampleOfA, throwOnUnresolved: false)
+              .map((a) => a.type.name),
+          ['A']);
+      expect(
+          $A
+              .firstAnnotationOfExact($ExampleOfA, throwOnUnresolved: false)
+              .type
+              .name,
+          'A');
+      expect(
+          $A
+              .annotationsOfExact($ExampleOfA, throwOnUnresolved: false)
+              .map((a) => a.type.name),
+          ['A']);
+    });
+  });
 }