Merge branch 'main' into misc/remove-unused-build-config

Author: parlough

lib/src/generator/templates.runtime_renderers.dart

@@ -2885,6 +2885,13 @@ class _Renderer_Container extends RendererBase<Container> {
                         _render_Operator(e, ast, r.template, sink, parent: r));
                   },
                 ),
+                'isDartCoreObject': Property(
+                  getValue: (CT_ c) => c.isDartCoreObject,
+                  renderVariable: (CT_ c, Property<CT_> self,
+                          List<String> remainingNames) =>
+                      self.renderSimpleVariable(c, remainingNames, 'bool'),
+                  getBool: (CT_ c) => c.isDartCoreObject,
+                ),
                 'isEnum': Property(
                   getValue: (CT_ c) => c.isEnum,
                   renderVariable: (CT_ c, Property<CT_> self,
@@ -16364,14 +16371,14 @@ const _invisibleGetters = {
     'hasFooterVersion',
     'hashCode',
     'implementers',
-    'inheritThrough',
     'inheritanceManager',
     'libraries',
     'libraryCount',
     'libraryExports',
     'localPackages',
     'localPublicLibraries',
     'name',
+    'objectClass',
     'packageGraph',
     'packageMap',
     'packageMeta',
@@ -16384,8 +16391,7 @@ const _invisibleGetters = {
     'referenceParents',
     'resourceProvider',
     'runtimeType',
-    'sdkLibrarySources',
-    'specialClasses'
+    'sdkLibrarySources'
   },
   'PackageMeta': {
     'dir',

lib/src/model/class.dart

@@ -45,7 +45,11 @@ class Class extends InheritingContainer with Constructable, MixedInTypes {
 
   Class(this.element, Library library, PackageGraph packageGraph)
       : super(library, packageGraph) {
-    packageGraph.specialClasses.addSpecial(this);
+    if (element.name == 'Object' &&
+        library.element.name == 'dart.core' &&
+        package.name == 'Dart') {
+      packageGraph.objectClass = this;
+    }
   }
 
   @override

lib/src/model/comment_referable.dart

@@ -223,14 +223,13 @@ extension on Scope {
 /// A set of utility methods for helping build
 /// [CommentReferable.referenceChildren] out of collections of other
 /// [CommentReferable]s.
-extension CommentReferableEntryGenerators on Iterable<CommentReferable> {
+extension CommentReferableEntryGenerators<T extends CommentReferable>
+    on Iterable<T> {
   /// Creates reference entries for this Iterable.
   ///
   /// If there is a conflict with [referable], the included [MapEntry] uses
   /// [referable]'s [CommentReferable.referenceName] as a prefix.
-  Map<String, CommentReferable> explicitOnCollisionWith(
-          CommentReferable referable) =>
-      {
+  Map<String, T> explicitOnCollisionWith(CommentReferable referable) => {
         for (var r in this)
           if (r.referenceName == referable.referenceName)
             '${referable.referenceName}.${r.referenceName}': r
@@ -239,13 +238,13 @@ extension CommentReferableEntryGenerators on Iterable<CommentReferable> {
       };
 
   /// A mapping from each [CommentReferable]'s name to itself.
-  Map<String, CommentReferable> get asMapByName => {
+  Map<String, T> get asMapByName => {
         for (var r in this) r.referenceName: r,
       };
 
   /// Returns all values not of this type.
-  List<CommentReferable> whereNotType<T>() => [
+  List<T> whereNotType<U>() => [
         for (var referable in this)
-          if (referable is! T) referable,
+          if (referable is! U) referable,
       ];
 }

lib/src/model/container.dart

@@ -49,6 +49,10 @@ abstract class Container extends ModelElement
   /// Whether this is a mixin.
   bool get isMixin => element is MixinElement;
 
+  /// Whether this container represents the Object class from 'dart:core'.
+  bool get isDartCoreObject =>
+      element.name == 'Object' && element.library?.name == 'dart.core';
+
   /// The model elements of all of the members of this container, including
   /// declared and inherited ones.
   Iterable<ModelElement> get allModelElements => [
@@ -156,33 +160,6 @@ abstract class Container extends ModelElement
   late final Set<Element> _allElements =
       allModelElements.map((e) => e.element).toSet();
 
-  late final Map<String, List<ModelElement>> _membersByName = () {
-    var membersByName = <String, List<ModelElement>>{};
-    for (var element in allModelElements) {
-      membersByName.putIfAbsent(element.name, () => []).add(element);
-    }
-    return membersByName;
-  }();
-
-  /// Given a [ModelElement] that is a member of some other class, returns
-  /// the member of this class that has the same name and runtime type.
-  ///
-  /// This enables object substitution for canonicalization, such as Interceptor
-  /// for Object.
-  T memberByExample<T extends ModelElement>(T example) {
-    // [T] is insufficiently specific to disambiguate between different
-    // subtypes of [Inheritable] or other mixins/implementations of
-    // [ModelElement] via [Iterable.whereType].
-    var possibleMembers = _membersByName[example.name]!
-        .where((e) => e.runtimeType == example.runtimeType);
-    if (example is Accessor) {
-      possibleMembers = possibleMembers
-          .where((e) => example.isGetter == (e as Accessor).isGetter);
-    }
-    assert(possibleMembers.length == 1);
-    return possibleMembers.first as T;
-  }
-
   bool get hasPublicStaticFields => staticFields.any((e) => e.isPublic);
 
   List<Field> get publicStaticFieldsSorted =>

lib/src/model/inheritable.dart

@@ -5,8 +5,8 @@
 import 'package:analyzer/dart/element/element.dart';
 import 'package:collection/collection.dart' show IterableExtension;
 import 'package:dartdoc/src/model/attribute.dart';
+import 'package:dartdoc/src/model/comment_referable.dart';
 import 'package:dartdoc/src/model/model.dart';
-import 'package:dartdoc/src/special_elements.dart';
 
 /// Mixin for subclasses of [ModelElement] representing elements that can be
 /// inherited from one class to another.
@@ -43,6 +43,9 @@ mixin Inheritable on ContainerMember {
       canonicalEnclosingContainer?.canonicalLibrary;
 
   @override
+  // TODO(srawlins): Do something about this overridden field. Maybe split out
+  // the super implementation.
+  // ignore: overridden_fields
   late final ModelElement? canonicalModelElement = canonicalEnclosingContainer
       ?.allCanonicalModelElements
       .firstWhereOrNull((m) =>
@@ -55,22 +58,40 @@ mixin Inheritable on ContainerMember {
       var searchElement = element.declaration;
       // TODO(jcollins-g): generate warning if an inherited element's definition
       // is in an intermediate non-canonical class in the inheritance chain?
-      Container? previous;
-      Container? previousNonSkippable;
       Container? found;
-      for (var c in _inheritance.reversed) {
-        // Filter out mixins.
-        if (c.containsElement(searchElement)) {
-          if ((packageGraph.inheritThrough.contains(previous) &&
-                  c != definingEnclosingContainer) ||
-              (packageGraph.inheritThrough.contains(c) &&
-                  c == definingEnclosingContainer)) {
-            return previousNonSkippable!
-                .memberByExample(this)
-                .canonicalEnclosingContainer;
+      var reverseInheritance = _inheritance.reversed.toList();
+      for (var i = 0; i < reverseInheritance.length; i++) {
+        var container = reverseInheritance[i];
+        if (container.containsElement(searchElement)) {
+          var previousIsHiddenAndNotDefining = i > 0 &&
+              _isHiddenInterface(reverseInheritance[i - 1]) &&
+              container != definingEnclosingContainer;
+          var thisIsHiddenAndDefining = _isHiddenInterface(container) &&
+              container == definingEnclosingContainer;
+          // If the previous container in the search is one of the "hidden"
+          // interfaces, and it's not this member's defining container, OR if
+          // this container in the search is one of the "hidden" interfaces,
+          // and it is also this member's defining container, then we can just
+          // immediately return the canonical enclosing container of the
+          // overridden member in the previous, non-hidden container in the
+          // inheritance.
+          if (previousIsHiddenAndNotDefining || thisIsHiddenAndDefining) {
+            var previousVisible = reverseInheritance
+                .take(i)
+                .lastWhere((e) => !_isHiddenInterface(e));
+            var membersInPreviousVisible = previousVisible.allModelElements
+                .where((e) => e.name == name)
+                .whereType<Inheritable>()
+                .whereNotType<Field>();
+            assert(
+                membersInPreviousVisible.length == 1,
+                'found multiple members named "$name" in '
+                '"${previousVisible.name}": '
+                '${membersInPreviousVisible.toList()}');
+            return membersInPreviousVisible.first.canonicalEnclosingContainer;
           }
-          var canonicalContainer =
-              packageGraph.findCanonicalModelElementFor(c) as Container?;
+          var canonicalContainer = packageGraph
+              .findCanonicalModelElementFor(container) as Container?;
           // TODO(jcollins-g): invert this lookup so traversal is recursive
           // starting from the ModelElement.
           if (canonicalContainer != null) {
@@ -80,10 +101,6 @@ mixin Inheritable on ContainerMember {
             break;
           }
         }
-        previous = c;
-        if (!packageGraph.inheritThrough.contains(c)) {
-          previousNonSkippable = c;
-        }
       }
       if (found != null) {
         return found;
@@ -96,6 +113,20 @@ mixin Inheritable on ContainerMember {
     return super.computeCanonicalEnclosingContainer();
   }
 
+  /// Whether [c] is a "hidden" interface.
+  ///
+  /// A hidden interface should never be considered the canonical enclosing
+  /// container of a container member.
+  ///
+  /// Add classes here if they are similar to the Dart SDK's 'Interceptor' class
+  /// in that they are to be ignored even when they are the implementers of
+  /// [Inheritable]s, and the class these inherit from should instead claim
+  /// implementation.
+  bool _isHiddenInterface(Container? c) =>
+      c != null &&
+      c.element.name == 'Interceptor' &&
+      c.element.library?.name == '_interceptors';
+
   /// A roughly ordered list of this element's enclosing container's inheritance
   /// chain.
   ///
@@ -104,10 +135,9 @@ mixin Inheritable on ContainerMember {
     var inheritance = [
       ...(enclosingElement as InheritingContainer).inheritanceChain,
     ];
-    var object = packageGraph.specialClasses[SpecialClass.object]!;
 
     assert(
-        definingEnclosingContainer == object ||
+        definingEnclosingContainer.isDartCoreObject ||
             inheritance.contains(definingEnclosingContainer), () {
       var inheritanceDescriptions = inheritance
           .map((e) =>
@@ -121,8 +151,8 @@ mixin Inheritable on ContainerMember {
     }());
     // Unless the code explicitly extends dart:core's Object, we won't get
     // an entry here.  So add it.
-    if (inheritance.last != object) {
-      inheritance.add(object);
+    if (!inheritance.last.isDartCoreObject) {
+      inheritance.add(packageGraph.objectClass);
     }
     return inheritance;
   }

lib/src/model/mixin.dart

@@ -9,7 +9,6 @@ import 'package:dartdoc/src/model/comment_referable.dart';
 import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/model_utils.dart' as model_utils;
-import 'package:dartdoc/src/special_elements.dart';
 import 'package:meta/meta.dart';
 
 class Mixin extends InheritingContainer {
@@ -20,8 +19,7 @@ class Mixin extends InheritingContainer {
     ...element.superclassConstraints
         .map((InterfaceType i) =>
             getTypeFor(i, library) as ParameterizedElementType)
-        .where((t) =>
-            t.modelElement != packageGraph.specialClasses[SpecialClass.object])
+        .where((t) => t.modelElement != packageGraph.objectClass)
   ];
 
   @override

lib/src/model/model_element.dart

@@ -14,7 +14,6 @@ import 'package:analyzer/source/line_info.dart';
 // ignore: implementation_imports
 import 'package:analyzer/src/dart/element/member.dart'
     show ExecutableMember, Member, ParameterMember;
-import 'package:collection/collection.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/model/annotation.dart';
 import 'package:dartdoc/src/model/attribute.dart';
@@ -27,7 +26,6 @@ import 'package:dartdoc/src/model_utils.dart';
 import 'package:dartdoc/src/render/parameter_renderer.dart';
 import 'package:dartdoc/src/runtime_stats.dart';
 import 'package:dartdoc/src/source_linker.dart';
-import 'package:dartdoc/src/special_elements.dart';
 import 'package:dartdoc/src/type_utils.dart';
 import 'package:dartdoc/src/warnings.dart';
 import 'package:meta/meta.dart';
@@ -385,10 +383,7 @@ abstract class ModelElement
   /// invalid code from analyzer's perspective, some are present in `sky_engine`
   /// (`@Native`) so we don't want to crash here.
   late final List<Annotation> annotations = element.metadata
-      .whereNot((m) =>
-          m.element == null ||
-          packageGraph.specialClasses[SpecialClass.pragma]!.element.constructors
-              .contains(m.element))
+      .where((m) => m.isVisibleAnnotation)
       .map((m) => Annotation(m, library, packageGraph))
       .toList(growable: false);
 
@@ -791,3 +786,19 @@ abstract class ModelElement
 
   String get linkedObjectType => _packageGraph.dartCoreObject;
 }
+
+extension on ElementAnnotation {
+  /// Whether this annotation should be displayed in documentation.
+  ///
+  /// At the moment, `pragma` is the only invisible annotation.
+  bool get isVisibleAnnotation {
+    if (element == null) return false;
+
+    if (element case ConstructorElement(:var enclosingElement3)) {
+      return !(enclosingElement3.name == 'pragma' &&
+          enclosingElement3.library.name == 'dart.core');
+    }
+
+    return true;
+  }
+}

lib/src/model/package_builder.dart

@@ -29,7 +29,6 @@ import 'package:dartdoc/src/package_config_provider.dart';
 import 'package:dartdoc/src/package_meta.dart'
     show PackageMeta, PackageMetaProvider;
 import 'package:dartdoc/src/runtime_stats.dart';
-import 'package:dartdoc/src/special_elements.dart';
 import 'package:meta/meta.dart';
 import 'package:path/path.dart' as p show Context;
 
@@ -479,13 +478,7 @@ class PubPackageBuilder implements PackageBuilder {
   /// Adds all libraries with documentable elements to
   /// [uninitializedPackageGraph].
   Future<void> _getLibraries(PackageGraph uninitializedPackageGraph) async {
-    var embedderSdk = _embedderSdk;
-    var findSpecialsSdk = switch (embedderSdk) {
-      EmbedderSdk(:var urlMappings) when urlMappings.isNotEmpty => embedderSdk,
-      _ => _sdk,
-    };
     var files = await _getFilesToDocument();
-    var specialFiles = specialLibraryFiles(findSpecialsSdk);
 
     logInfo('Discovering libraries...');
     var foundLibraries = <LibraryElement>{};
@@ -495,12 +488,7 @@ class PubPackageBuilder implements PackageBuilder {
       files,
     );
     _checkForMissingIncludedFiles(foundLibraries);
-    await _discoverLibraries(
-      uninitializedPackageGraph.addSpecialLibraryToGraph,
-      foundLibraries,
-      specialFiles.difference(files),
-      addingSpecials: true,
-    );
+    uninitializedPackageGraph.allLibrariesAdded = true;
   }
 
   /// Throws an exception if any configured-to-be-included files were not found