Merge branch 'main' into fix-wildcards

srawlins · srawlins · commit 422a1aedc0b8 · 2024-09-03T15:11:08.000-07:00
diff --git a/lib/resources/docs.dart.js.map b/lib/resources/docs.dart.js.map
diff --git a/lib/src/model/canonicalization.dart b/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(
diff --git a/lib/src/model/container.dart b/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;
diff --git a/lib/src/model/model_element.dart b/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);
diff --git a/lib/src/model/model_function.dart b/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;
diff --git a/lib/src/model/package_graph.dart b/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;
     }
diff --git a/lib/src/model/top_level_variable.dart b/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;
diff --git a/lib/src/model/typedef.dart b/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;
diff --git a/lib/src/model_utils.dart b/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;
   }
 }
diff --git a/lib/src/search.dart b/lib/src/search.dart
@@ -130,6 +130,13 @@ class IndexItem {
     EnclosedBy? enclosedBy;
     if (data['enclosedBy'] != null) {
       final map = data['enclosedBy'] as Map<String, dynamic>;
+      assert(
+        map['href'] != null,
+        "'enclosedBy' element expected to have a non-null 'href', "
+        "but was null: '${data['qualifiedName']}', "
+        "enclosed by the ${Kind.values[map['kind'] as int]} '${map['name']}' "
+        "('${map['qualifiedName']}')",
+      );
       enclosedBy = EnclosedBy._(
           name: map['name'] as String,
           kind: Kind.values[map['kind'] as int],
diff --git a/test/dartdoc_test_base.dart b/test/dartdoc_test_base.dart
@@ -102,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);
diff --git a/test/libraries_test.dart b/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');
+  }
+}
diff --git a/test/prefixes_test.dart b/test/prefixes_test.dart
@@ -38,6 +38,7 @@ int x = 0;
     );
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/dartdoc/issues/3769')
   void test_referenced_wildcard() async {
     var library = await bootPackageWithLibrary(
       '''
diff --git a/test/src/test_descriptor_utils.dart b/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;
   }
diff --git a/tool/task.dart b/tool/task.dart
@@ -23,14 +23,15 @@ import 'src/warnings_collection.dart';
 void main(List<String> args) async {
   var parser = ArgParser()
     ..addCommand('analyze')
-    ..addCommand('build')
     ..addCommand('buildbot')
     ..addCommand('clean')
     ..addCommand('compare')
     ..addCommand('help')
     ..addCommand('test')
     ..addCommand('try-publish')
     ..addCommand('validate');
+  var buildCommand = parser.addCommand('build')
+    ..addFlag('debug', help: 'build unoptimized JavaScript');
   var docCommand = parser.addCommand('doc')
     ..addOption('name', help: 'package name')
     ..addOption('version', help: 'package version')
@@ -45,6 +46,7 @@ void main(List<String> args) async {
     return;
   }
 
+  buildUsage = buildCommand.usage;
   docUsage = docCommand.usage;
   serveUsage = serveCommand.usage;
 
@@ -64,6 +66,7 @@ void main(List<String> args) async {
   };
 }
 
+late String buildUsage;
 late String docUsage;
 late String serveUsage;
 
@@ -116,15 +119,24 @@ Future<void> analyzeTestPackages() async {
   }
 }
 
+Future<void> _buildHelp() async {
+  print('''
+Usage:
+dart tool/task.dart build [renderers|dartdoc-options|web]
+$buildUsage
+''');
+}
+
 Future<void> runBuild(ArgResults commandResults) async {
   if (commandResults.rest.isEmpty) {
     await buildAll();
   }
+  var debug = (commandResults['debug'] ?? false) as bool;
   for (var target in commandResults.rest) {
     await switch (target) {
       'renderers' => buildRenderers(),
       'dartdoc-options' => buildDartdocOptions(),
-      'web' => buildWeb(),
+      'web' => buildWeb(debug: debug),
       _ => throw UnimplementedError('Unknown build target: "$target"'),
     };
   }
@@ -154,13 +166,14 @@ Future<void> buildDartdocOptions() async {
 ''');
 }
 
-Future<void> buildWeb() async {
+Future<void> buildWeb({bool debug = false}) async {
   await SubprocessLauncher('build').runStreamedDartCommand([
     'compile',
     'js',
     '--output=lib/resources/docs.dart.js',
     'web/docs.dart',
-    '-O4',
+    if (debug) '--enable-asserts',
+    debug ? '-O0' : '-O4',
   ]);
   _delete(File('lib/resources/docs.dart.js.deps'));
 
@@ -294,7 +307,7 @@ Future<void> runDoc(ArgResults commandResults) async {
     throw ArgumentError('"doc" command requires a single target.');
   }
   var target = commandResults.rest.single;
-  var stats = commandResults['stats'];
+  var stats = commandResults['stats'] as bool;
   await switch (target) {
     'flutter' => docFlutter(withStats: stats),
     'help' => _docHelp(),
@@ -616,6 +629,7 @@ Help usage:
   }
   var command = commandResults.rest.single;
   return switch (command) {
+    'build' => _buildHelp(),
     'doc' => _docHelp(),
     'serve' => _serveHelp(),
     _ => throw UnimplementedError(

Original file line number	Diff line number	Diff line change
`@@ -72,19 +72,6 @@ extension ElementExtension on Element {`
`72`	`72`	`return true;`
`73`	`73`	`}`
`74`	`74`	`}`
`75`		`- if (self is LibraryElement) {`
`76`		`- if (self.identifier.startsWith('dart:_') \|\|`
`77`		`- self.identifier.startsWith('dart:nativewrappers/') \|\|`
`78`		`- 'dart:nativewrappers' == self.identifier) {`
`79`		`- return true;`
`80`		`- }`
`81`		`- var elementUri = self.source.uri;`
`82`		`- // TODO(jcollins-g): Implement real cross package detection.`
`83`		`- if (elementUri.scheme == 'package' &&`
`84`		`- elementUri.pathSegments[1] == 'src') {`
`85`		`- return true;`
`86`		`- }`
`87`		`- }`
`88`	`75`	`return false;`
`89`	`76`	`}`
`90`	`77`	`}`