blob: 73a96159d5e62a0f9439b4370bca88e7ca7269a4 [file] [edit]
// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
import 'dart:async';
import 'package:analyzer/dart/constant/value.dart';
import 'package:analyzer/dart/element/element.dart';
import 'package:analyzer/dart/element/nullability_suffix.dart';
import 'package:analyzer/dart/element/type.dart';
import 'package:build/build.dart';
import 'package:code_builder/code_builder.dart' hide FunctionType, RecordType;
import 'package:code_builder/code_builder.dart'
as cb
show FunctionType, RecordType;
import 'package:collection/collection.dart';
import 'package:path/path.dart' as p;
import 'package:source_gen/source_gen.dart' as source_gen show LibraryBuilder;
import 'package:source_gen/source_gen.dart' hide LibraryBuilder;
import 'annotation.dart';
Builder checksBuilder(BuilderOptions? _) => source_gen.LibraryBuilder(
const ChecksGenerator(),
generatedExtension: '.checks.dart',
);
final class ChecksGenerator extends GeneratorForAnnotation<CheckExtensions> {
const ChecksGenerator();
@override
Future<String> generateForAnnotatedDirective(
ElementDirective directive,
ConstantReader annotation,
BuildStep buildStep,
) async {
final basename = p.url.basenameWithoutExtension(buildStep.inputId.path);
final expectedImport = '$basename.checks.dart';
if (directive
case LibraryImport(:final DirectiveUriWithRelativeUri uri) ||
LibraryExport(:final DirectiveUriWithRelativeUri uri)
when uri.relativeUriString == expectedImport) {
// Annotation is on the correct import or export
} else {
throw InvalidGenerationSourceError(
'must annotate an import or export of $expectedImport',
);
}
final typesField = annotation.read('types');
if (!typesField.isList) {
throw InvalidGenerationSourceError(
'Failed to resolve the specified types. '
'Check for a missing build dependency.',
);
}
final targets = [
for (final object in typesField.listValue) _CheckTarget(object),
];
final referencedElements = <InterfaceElement>{};
for (final target in targets) {
referencedElements.add(target.element);
for (final (field: _, :type) in target.fields) {
_collectElements(type, referencedElements);
}
}
final importUris = await _resolveImports(
directive.libraryFragment,
referencedElements,
buildStep.resolver,
buildStep.inputId.path,
);
final library = Library(
(b) => b
..body.addAll([
for (final target in targets) _createExtension(target, importUris),
])
..directives.add(
Directive(
(b) => b
..type = DirectiveType.import
..url = 'package:checks/checks.dart',
),
),
);
final emitter = DartEmitter.scoped(
useNullSafetySyntax: true,
orderDirectives: true,
);
return library.accept(emitter).toString();
}
@override
dynamic generateForAnnotatedElement(
Element element,
ConstantReader annotation,
BuildStep buildStep,
) {
final basename = p.url.basenameWithoutExtension(buildStep.inputId.path);
throw InvalidGenerationSourceError(
'must annotate an import or export of $basename.checks.dart',
element: element,
);
}
Extension _createExtension(
_CheckTarget target,
Map<InterfaceElement, String> importUris,
) {
final element = target.element;
return Extension(
(b) => b
..name = '${element.displayName}Checks'
..on = TypeReference(
(b) => b
..symbol = 'Subject'
..url = 'package:checks/context.dart'
..types.add(refer(element.displayName, importUris[element])),
)
..methods.addAll([
for (final (:field, :type) in target.fields)
_createHasGetter(field, type, importUris),
]),
);
}
Method _createHasGetter(
FieldElement field,
DartType type,
Map<InterfaceElement, String> importUris,
) {
final name = field.name!;
final Reference typeReference;
try {
typeReference = _typeReference(type, importUris);
} on _UnresolvedType {
throw InvalidGenerationSourceError(
'Failed to resolve the type of '
'`${field.enclosingElement.displayName}.$name`. '
'Check for a missing build dependency.',
element: field,
);
}
return Method(
(b) => b
..name = name
..type = MethodType.getter
..returns = TypeReference(
(b) => b
..symbol = 'Subject'
..url = 'package:checks/context.dart'
..types.add(typeReference),
)
..lambda = true
..body = refer('has2').call([
literalString(name),
Method(
(b) => b
..lambda = true
..requiredParameters.add(Parameter((b) => b..name = 'v'))
..body = refer('v').property(name).code,
).closure,
]).code,
);
}
/// Adds the element of every interface type within [type] to [elements].
///
/// Must visit every interface type that [_typeReference] references, so
/// that an import is resolved for each of them.
static void _collectElements(DartType type, Set<InterfaceElement> elements) {
switch (type) {
case InterfaceType(:final element, :final typeArguments):
elements.add(element);
for (final typeArgument in typeArguments) {
_collectElements(typeArgument, elements);
}
case FunctionType():
for (final typeParameter in type.typeParameters) {
if (typeParameter.bound case final bound?) {
_collectElements(bound, elements);
}
}
_collectElements(type.returnType, elements);
for (final parameter in type.formalParameters) {
_collectElements(parameter.type, elements);
}
case RecordType(:final positionalFields, :final namedFields):
for (final field in positionalFields) {
_collectElements(field.type, elements);
}
for (final field in namedFields) {
_collectElements(field.type, elements);
}
}
}
/// A reference to [type] which imports the libraries for every element
/// referenced within [type].
///
/// The only type parameters which may be referenced within [type] are those
/// of generic function types within [type], which are in scope where they
/// are referenced.
///
/// Throws an [_UnresolvedType] if any type within [type] failed to resolve.
static Reference _typeReference(
DartType type,
Map<InterfaceElement, String> importUris,
) {
final isNullable = type.nullabilitySuffix == NullabilitySuffix.question;
return switch (type) {
DynamicType() => refer('dynamic'),
VoidType() => refer('void'),
NeverType() => TypeReference(
(b) => b
..symbol = 'Never'
..url = 'dart:core'
..isNullable = isNullable,
),
InterfaceType() => _interfaceTypeReference(type, importUris),
TypeParameterType(:final element) => TypeReference(
(b) => b
..symbol = element.name
..isNullable = isNullable,
),
FunctionType() => _functionTypeReference(type, importUris),
RecordType() => _recordTypeReference(type, importUris),
_ => throw const _UnresolvedType(),
};
}
static Reference _interfaceTypeReference(
InterfaceType type,
Map<InterfaceElement, String> importUris,
) => TypeReference(
(b) => b
..symbol = type.element.name
..url = importUris[type.element]!
..types.addAll([
for (final typeArgument in type.typeArguments)
_typeReference(typeArgument, importUris),
])
..isNullable = type.nullabilitySuffix == NullabilitySuffix.question,
);
static Reference _functionTypeReference(
FunctionType type,
Map<InterfaceElement, String> importUris,
) {
final typeParameters = [
for (final typeParameter in type.typeParameters)
TypeReference(
(b) => b
..symbol = typeParameter.name
..bound = switch (typeParameter.bound) {
final bound? => _typeReference(bound, importUris),
null => null,
},
),
];
final returnType = _typeReference(type.returnType, importUris);
final requiredParameters = <Reference>[];
final optionalParameters = <Reference>[];
final namedParameters = <String, Reference>{};
final namedRequiredParameters = <String, Reference>{};
for (final parameter in type.formalParameters) {
final parameterType = _typeReference(parameter.type, importUris);
if (parameter.isRequiredPositional) {
requiredParameters.add(parameterType);
} else if (parameter.isOptionalPositional) {
optionalParameters.add(parameterType);
} else if (parameter.isRequiredNamed) {
namedRequiredParameters[parameter.name!] = parameterType;
} else {
namedParameters[parameter.name!] = parameterType;
}
}
return cb.FunctionType(
(b) => b
..returnType = returnType
..types.addAll(typeParameters)
..requiredParameters.addAll(requiredParameters)
..optionalParameters.addAll(optionalParameters)
..namedParameters.addAll(namedParameters)
..namedRequiredParameters.addAll(namedRequiredParameters)
..isNullable = type.nullabilitySuffix == NullabilitySuffix.question,
);
}
static Reference _recordTypeReference(
RecordType type,
Map<InterfaceElement, String> importUris,
) => cb.RecordType(
(b) => b
..positionalFieldTypes.addAll([
for (final field in type.positionalFields)
_typeReference(field.type, importUris),
])
..namedFieldTypes.addAll({
for (final field in type.namedFields)
field.name: _typeReference(field.type, importUris),
})
..isNullable = type.nullabilitySuffix == NullabilitySuffix.question,
);
/// The URI to import for each of [elements].
///
/// Elements declared in public SDK libraries are imported from their
/// declaring library. Other elements are imported from the first library
/// which exports them, searching in order:
///
/// 1. The imports of [testLibrary].
/// 2. The imports of the libraries which declare [elements].
/// 3. For elements declared in private SDK libraries, the public SDK
/// libraries, see [_findPublicSdkLibraries].
///
/// Within the first two groups libraries outside of `src/` are searched
/// first.
///
/// If no library exports an element it is imported from its declaring
/// library, which may be under `src/`. It is an error if that library is a
/// private SDK library, since it cannot be imported.
static Future<Map<InterfaceElement, String>> _resolveImports(
LibraryFragment testLibrary,
Set<InterfaceElement> elements,
Resolver resolver,
String entryAssetPath,
) async {
final declaringLibraries = {
for (final element in elements) element.library,
};
final candidates = [
...testLibrary.importedLibraries
.whereNot(_isPrivateSdkLibrary)
.sorted(_compareLibraries),
...{
for (final library in declaringLibraries)
for (final fragment in library.fragments)
...fragment.importedLibraries,
}.whereNot(_isPrivateSdkLibrary).sorted(_compareLibraries),
];
List<LibraryElement>? publicSdkLibraries;
final importUris = <InterfaceElement, String>{};
for (final element in elements) {
final declaringLibrary = element.library;
if (_isPublicSdkLibrary(declaringLibrary)) {
importUris[element] = declaringLibrary.uri.toString();
continue;
}
var exportingLibrary = _findExportOf(candidates, element);
if (exportingLibrary == null && _isPrivateSdkLibrary(declaringLibrary)) {
publicSdkLibraries ??= await _findPublicSdkLibraries([
testLibrary.element,
...declaringLibraries,
], resolver);
exportingLibrary =
_findExportOf(publicSdkLibraries, element) ??
(throw InvalidGenerationSourceError(
'Cannot import `${element.displayName}`. It is declared in '
'${declaringLibrary.uri} and not exported by any public '
'library.',
));
}
importUris[element] = await _importUriFor(
exportingLibrary ?? declaringLibrary,
resolver,
entryAssetPath,
);
}
return importUris;
}
/// Returns the first library in [candidates] which exports [element], if
/// any.
static LibraryElement? _findExportOf(
Iterable<LibraryElement> candidates,
InterfaceElement element,
) {
final name = element.name;
if (name == null) return null;
return candidates.firstWhereOrNull(
(library) => library.exportNamespace.get2(name) == element,
);
}
/// The public SDK libraries to search for elements declared in private SDK
/// libraries.
///
/// Libraries reachable through imports and exports from [roots] come first,
/// since they are available on the platform the program targets. Some
/// elements are exported by multiple public SDK libraries for different
/// platforms, for instance `HttpStatus` from both `dart:io` and `dart:html`.
/// The remaining public SDK libraries known to [resolver] follow. Each group
/// is sorted by URI.
static Future<List<LibraryElement>> _findPublicSdkLibraries(
Iterable<LibraryElement> roots,
Resolver resolver,
) async {
final reachable = <LibraryElement>{};
final toVisit = [...roots];
while (toVisit.isNotEmpty) {
final library = toVisit.removeLast();
if (!reachable.add(library)) continue;
for (final fragment in library.fragments) {
toVisit.addAll(fragment.importedLibraries);
}
toVisit.addAll(library.exportedLibraries);
}
final allLibraries = await resolver.libraries.toList();
String uri(LibraryElement library) => library.uri.toString();
return [
...reachable.where(_isPublicSdkLibrary).sortedBy(uri),
...allLibraries
.where(_isPublicSdkLibrary)
.whereNot(reachable.contains)
.sortedBy(uri),
];
}
/// The URI to use in the generated library to import [library].
static Future<String> _importUriFor(
LibraryElement library,
Resolver resolver,
String entryAssetPath,
) async {
if (library.isInSdk) return library.uri.toString();
try {
final assetId = await resolver.assetIdForElement(library);
if (assetId.path.startsWith('lib/')) {
return assetId.uri.toString();
} else {
return p.url.relative(assetId.path, from: p.dirname(entryAssetPath));
}
} on UnresolvableAssetException {
// Asset may be in a summary.
return library.uri.toString();
}
}
static bool _isPrivateSdkLibrary(LibraryElement library) =>
library.isInSdk && library.uri.path.startsWith('_');
static bool _isPublicSdkLibrary(LibraryElement library) =>
library.isInSdk && !library.uri.path.startsWith('_');
/// Orders libraries by scheme, then libraries outside of `src/` first, then
/// by path.
static int _compareLibraries(LibraryElement a, LibraryElement b) {
final schemeComparison = a.uri.scheme.compareTo(b.uri.scheme);
if (schemeComparison != 0) return schemeComparison;
final aIsSrc = a.uri.path.contains('/src/');
final bIsSrc = b.uri.path.contains('/src/');
if (aIsSrc != bIsSrc) return aIsSrc ? 1 : -1;
return a.uri.path.compareTo(b.uri.path);
}
}
/// A class to generate a checks extension for.
final class _CheckTarget {
final InterfaceElement element;
/// The fields to generate getters for, with their types.
///
/// Includes public instance fields other than `hashCode` that have a getter
/// whose return type does not reference any private types.
///
/// The extension is on the raw type, so field types are read from the type
/// instantiated to bounds to match the static type of `v.field`.
final List<({FieldElement field, DartType type})> fields;
_CheckTarget._(this.element, this.fields);
factory _CheckTarget(DartObject dartObject) {
final type = dartObject.toTypeValue();
if (type is! InterfaceType) {
throw InvalidGenerationSourceError(
'Only interface types may be used for checks extensions: $type',
);
}
final element = type.element;
if (element.isPrivate) {
throw InvalidGenerationSourceError(
'Private types cannot be used for checks extensions: '
'`${element.displayName}`',
element: element,
);
}
final rawType = element.library.typeSystem.instantiateInterfaceToBounds(
element: element,
nullabilitySuffix: NullabilitySuffix.none,
);
return _CheckTarget._(element, [
for (final field in element.fields)
if (field.name != 'hashCode' && !field.isStatic && !field.isPrivate)
if (rawType.getGetter(field.name!) case final getter?
when !_referencesPrivateType(getter.returnType))
(field: field, type: getter.returnType),
]);
}
static bool _referencesPrivateType(DartType type) => switch (type) {
InterfaceType(:final element, :final typeArguments) =>
element.isPrivate || typeArguments.any(_referencesPrivateType),
FunctionType(
:final typeParameters,
:final returnType,
:final formalParameters,
) =>
typeParameters.any(
(p) => p.bound != null && _referencesPrivateType(p.bound!),
) ||
_referencesPrivateType(returnType) ||
formalParameters.any((p) => _referencesPrivateType(p.type)),
RecordType(:final positionalFields, :final namedFields) =>
positionalFields.any((f) => _referencesPrivateType(f.type)) ||
namedFields.any((f) => _referencesPrivateType(f.type)),
_ => false,
};
}
/// Thrown by [ChecksGenerator._typeReference] when a type failed to resolve.
///
/// Caught where the field that has the type is known so that the reported
/// error can point to it.
final class _UnresolvedType implements Exception {
const _UnresolvedType();
}