Fix many library sidebars, and search (#3865)

The library sidebars on container (e.g. Class), top-level variable, top-level
function, and typedefs were totally busted, as a result of
d629e1e.

Fixes #3859 and fixes
#3861.

The fix is to allow a Library's `canonicalModelElement` to be it's canonical
library, instead of `null`. This involves adding a few checks for "am I
calculating something for a Library?" and moving some "is this library
considered public" logic out of `Element.hasPrivateName` and into
`ModelElement.isPublic`. That corrects the issue of an exported Class's (for
example) enclosing element's URI, for the search results.

Once all of that is fixed, we also correct the `aboveSidebarPath`
implementation for a few elements, to point to the _canonical_ library's
sidebar path.

This fix highlights an issue with wildcard-variables, so one test is newly
marked as failing.

Author: srawlins

lib/src/model/canonicalization.dart

@@ -74,6 +74,11 @@ final class Canonicalization {
       scoredCandidate._alterScore(1.0, _Reason.packageName);
     }
 
+    // Same idea as the above, for the Dart SDK.
+    if (library.name == 'dart:core') {
+      scoredCandidate._alterScore(0.9, _Reason.packageName);
+    }
+
     // Give a tiny boost for libraries with long names, assuming they're
     // more specific (and therefore more likely to be the owner of this symbol).
     scoredCandidate._alterScore(

lib/src/model/container.dart

@@ -238,7 +238,7 @@ abstract class Container extends ModelElement
   String get sidebarPath;
 
   @override
-  String get aboveSidebarPath => library.sidebarPath;
+  String get aboveSidebarPath => canonicalLibraryOrThrow.sidebarPath;
 
   @override
   String get belowSidebarPath => sidebarPath;

lib/src/model/model_element.dart

@@ -394,6 +394,22 @@ abstract class ModelElement
         !(enclosingElement as Extension).isPublic) {
       return false;
     }
+
+    if (element case LibraryElement(:var identifier, :var source)) {
+      // Private Dart SDK libraries are not public.
+      if (identifier.startsWith('dart:_') ||
+          identifier.startsWith('dart:nativewrappers/') ||
+          'dart:nativewrappers' == identifier) {
+        return false;
+      }
+      // Package-private libraries are not public.
+      var elementUri = source.uri;
+      if (elementUri.scheme == 'package' &&
+          elementUri.pathSegments[1] == 'src') {
+        return false;
+      }
+    }
+
     return !element.hasPrivateName && !hasNodoc;
   }();
 
@@ -518,6 +534,7 @@ abstract class ModelElement
     final candidateLibraries = thisAndExported.where((l) {
       if (!l.isPublic) return false;
       if (l.package.documentedWhere == DocumentLocation.missing) return false;
+      if (this is Library) return true;
       var lookup = l.element.exportNamespace.definedNames[topLevelElementName];
       return topLevelElement ==
           (lookup is PropertyAccessorElement ? lookup.variable2 : lookup);

lib/src/model/model_function.dart

@@ -51,7 +51,7 @@ class ModelFunctionTyped extends ModelElement with TypeParameters {
   String get filePath => '${canonicalLibrary?.dirName}/$fileName';
 
   @override
-  String get aboveSidebarPath => enclosingElement.sidebarPath;
+  String get aboveSidebarPath => canonicalLibraryOrThrow.sidebarPath;
 
   @override
   String? get belowSidebarPath => null;

lib/src/model/package_graph.dart

@@ -195,6 +195,7 @@ class PackageGraph with CommentReferable, Nameable {
       // that might not _have_ a canonical [ModelElement], too.
       if (element.isCanonical ||
           element.canonicalModelElement == null ||
+          element is Library ||
           element.enclosingElement!.isCanonical) {
         for (var d in element.documentationFrom
             .where((d) => d.hasDocumentationComment)) {
@@ -771,6 +772,8 @@ class PackageGraph with CommentReferable, Nameable {
       if (canonicalClass != null) preferredClass = canonicalClass;
     }
     var lib = modelElement.canonicalLibrary;
+    if (modelElement is Library) return lib;
+
     if (lib == null && preferredClass != null) {
       lib = preferredClass.canonicalLibrary;
     }

lib/src/model/top_level_variable.dart

@@ -45,7 +45,7 @@ class TopLevelVariable extends ModelElement
   String get filePath => '${canonicalLibraryOrThrow.dirName}/$fileName';
 
   @override
-  String get aboveSidebarPath => enclosingElement.sidebarPath;
+  String get aboveSidebarPath => canonicalLibraryOrThrow.sidebarPath;
 
   @override
   String? get belowSidebarPath => null;

lib/src/model/typedef.dart

@@ -35,7 +35,7 @@ abstract class Typedef extends ModelElement
   String get filePath => '${canonicalLibraryOrThrow.dirName}/$fileName';
 
   @override
-  String get aboveSidebarPath => enclosingElement.sidebarPath;
+  String get aboveSidebarPath => canonicalLibraryOrThrow.sidebarPath;
 
   @override
   String? get belowSidebarPath => null;

lib/src/model_utils.dart

@@ -72,19 +72,6 @@ extension ElementExtension on Element {
         return true;
       }
     }
-    if (self is LibraryElement) {
-      if (self.identifier.startsWith('dart:_') ||
-          self.identifier.startsWith('dart:nativewrappers/') ||
-          'dart:nativewrappers' == self.identifier) {
-        return true;
-      }
-      var elementUri = self.source.uri;
-      // TODO(jcollins-g): Implement real cross package detection.
-      if (elementUri.scheme == 'package' &&
-          elementUri.pathSegments[1] == 'src') {
-        return true;
-      }
-    }
     return false;
   }
 }

test/dartdoc_test_base.dart

@@ -36,6 +36,9 @@ abstract class DartdocTestBase {
 
   String get linkPrefix => '$placeholder$libraryName';
 
+  String get dartAsyncUrlPrefix =>
+      'https://api.dart.dev/stable/3.2.0/dart-async';
+
   String get dartCoreUrlPrefix => 'https://api.dart.dev/stable/3.2.0/dart-core';
 
   String get sdkConstraint => '>=3.3.0 <4.0.0';
@@ -99,20 +102,21 @@ analyzer:
   /// Creates a single library named [libraryName], with optional preamble
   /// [libraryPreamble].  Optionally, pass [extraFiles] such as
   /// `dartdoc_options.yaml`.
-  Future<Library> bootPackageWithLibrary(String libraryContent,
-      {String libraryPreamble = '',
-      Iterable<d.Descriptor> extraFiles = const [],
-      List<String> additionalArguments = const []}) async {
+  Future<Library> bootPackageWithLibrary(
+    String libraryContent, {
+    String libraryFilePath = 'lib/library.dart',
+    String libraryPreamble = '',
+    Iterable<d.Descriptor> extraFiles = const [],
+    List<String> additionalArguments = const [],
+  }) async {
     return (await bootPackageFromFiles([
-      d.dir('lib', [
-        d.file('lib.dart', '''
+      d.file(libraryFilePath, '''
 $libraryPreamble
 library $libraryName;
 
 $libraryContent
 '''),
-      ]),
-      ...extraFiles
+      ...extraFiles,
     ], additionalArguments: additionalArguments))
         .libraries
         .named(libraryName);

test/libraries_test.dart

@@ -5,13 +5,19 @@
 import 'package:analyzer/file_system/memory_file_system.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:test/test.dart';
+import 'package:test_reflective_loader/test_reflective_loader.dart';
 
+import 'dartdoc_test_base.dart';
 import 'src/test_descriptor_utils.dart' as d;
 import 'src/utils.dart';
 
-// TODO(srawlins): Migrate to test_reflective_loader tests.
-
 void main() {
+  defineReflectiveSuite(() {
+    defineReflectiveTests(LibrariesTest);
+  });
+
+  // TODO(srawlins): Migrate to test_reflective_loader tests.
+
   test('A named library', () async {
     var packageMetaProvider = testPackageMetaProvider;
 
@@ -169,3 +175,35 @@ A doc comment.
         '${htmlBasePlaceholder}dart-async/dart-async-library.html');
   }, onPlatform: {'windows': Skip('Test does not work on Windows (#2446)')});
 }
+
+@reflectiveTest
+class LibrariesTest extends DartdocTestBase {
+  @override
+  String get libraryName => 'libraries';
+
+  void test_publicLibrary() async {
+    var library = await bootPackageWithLibrary(
+      'var x = 1;',
+      libraryFilePath: 'lib/library.dart',
+    );
+
+    expect(library.qualifiedName, 'libraries');
+    expect(library.href, '${placeholder}libraries/libraries-library.html');
+  }
+
+  void test_exportedLibrary() async {
+    var library = await bootPackageWithLibrary(
+      'var x = 1;',
+      libraryFilePath: 'lib/src/library.dart',
+      extraFiles: [
+        d.dir('lib', [
+          d.file('public.dart', '''
+export 'src/library.dart';
+''')
+        ]),
+      ],
+    );
+    expect(library.qualifiedName, 'libraries');
+    expect(library.href, '${placeholder}public/public-library.html');
+  }
+}

test/prefixes_test.dart

@@ -29,11 +29,14 @@ int x = 0;
 ''',
       additionalArguments: ['--link-to-remote'],
     );
-    var f = library.properties.named('x');
-    // There is no link, but also no wrong link or crash.
-    expect(f.documentationAsHtml, '<p>Text <code>async</code>.</p>');
+    var x = library.properties.named('x');
+    expect(
+      x.documentationAsHtml,
+      '<p>Text <a href="$dartAsyncUrlPrefix/dart-async-library.html">async</a>.</p>',
+    );
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/dartdoc/issues/3769')
   void test_referenced_wildcard() async {
     var library = await bootPackageWithLibrary(
       '''
@@ -44,8 +47,8 @@ int x = 0;
 ''',
       additionalArguments: ['--link-to-remote'],
     );
-    var f = library.properties.named('x');
+    var x = library.properties.named('x');
     // There is no link, but also no wrong link or crash.
-    expect(f.documentationAsHtml, '<p>Text <code>_</code>.</p>');
+    expect(x.documentationAsHtml, '<p>Text <code>_</code>.</p>');
   }
 }

test/src/test_descriptor_utils.dart

@@ -131,7 +131,8 @@ extension on d.FileDescriptor {
   Future<String> createInMemory(
       MemoryResourceProvider resourceProvider, String parent) async {
     var content = await readAsBytes().transform(utf8.decoder).join('');
-    var fullPath = resourceProvider.pathContext.join(parent, name);
+    var fullPath = resourceProvider
+        .convertPath(resourceProvider.pathContext.join(parent, name));
     resourceProvider.newFile(fullPath, content);
     return fullPath;
   }