Write canonicalized SDK

Author: srawlins

analysis_options.yaml

@@ -6,6 +6,7 @@ analyzer:
   errors:
     unused_import: warning
     unused_shown_name: warning
+    todo: ignore
   exclude:
     - 'doc/**'
     - 'lib/src/third_party/pkg/**'

lib/src/dartdoc_options.dart

@@ -669,8 +669,8 @@ abstract class DartdocOption<T> {
   String get _directoryCurrentPath => resourceProvider.pathContext.current;
 
   /// Calls [valueAt] on the directory this element is defined in.
-  T valueAtElement(Element element) => valueAt(resourceProvider.getFolder(
-      resourceProvider.pathContext.canonicalize(
+  T valueAtElement(Element element) =>
+      valueAt(resourceProvider.getFolder(resourceProvider.pathContext.normalize(
           resourceProvider.pathContext.basename(element.source.fullName))));
 
   /// Adds a DartdocOption to the children of this DartdocOption.

lib/src/model/documentable.dart

@@ -30,9 +30,9 @@ abstract class Documentable extends Nameable {
 }
 
 /// For a given package, indicate with this enum whether it should be documented
-/// [local]ly, whether we should treat the package as [missing] and any references
-/// to it made canonical to this package, or [remote], indicating that
-/// we can build hrefs to an external source.
+/// [local]ly, whether we should treat the package as [missing] and any
+/// references to it made canonical to this package, or [remote], indicating
+/// that we can build hrefs to an external source.
 enum DocumentLocation {
   local,
   missing,

lib/src/model/package.dart

@@ -12,7 +12,9 @@ import 'package:dartdoc/src/warnings.dart';
 import 'package:path/path.dart' as path;
 import 'package:pub_semver/pub_semver.dart';
 
-final RegExp substituteNameVersion = RegExp(r'%([bnv])%');
+@Deprecated('Public variable intended to be private; will be removed as early '
+    'as Dartdoc 1.0.0')
+RegExp get substituteNameVersion => Package._substituteNameVersion;
 
 // All hrefs are emitted as relative paths from the output root. We are unable
 // to compute them from the page we are generating, and many properties computed
@@ -224,51 +226,56 @@ class Package extends LibraryContainer
   String _baseHref;
 
   String get baseHref {
-    if (_baseHref == null) {
-      if (documentedWhere == DocumentLocation.remote) {
-        _baseHref =
-            config.linkToUrl.replaceAllMapped(substituteNameVersion, (m) {
-          switch (m.group(1)) {
-            // Return the prerelease tag of the release if a prerelease,
-            // or 'stable' otherwise. Mostly coded around
-            // the Dart SDK's use of dev/stable, but theoretically applicable
-            // elsewhere.
-            case 'b':
-              {
-                var version = Version.parse(packageMeta.version);
-                var tag = 'stable';
-                if (version.isPreRelease) {
-                  // version.preRelease is a List<dynamic> with a mix of
-                  // integers and strings.  Given this, handle
-                  // 2.8.0-dev.1.0, 2.9.0-1.0.dev, and similar
-                  // variations.
-                  tag = version.preRelease.whereType<String>().first;
-                  // Who knows about non-SDK packages, but assert that SDKs
-                  // must conform to the known format.
-                  assert(
-                      packageMeta.isSdk == false || int.tryParse(tag) == null,
-                      'Got an integer as string instead of the expected "dev" tag');
-                }
-                return tag;
-              }
-            case 'n':
-              return name;
-            // The full version string of the package.
-            case 'v':
-              return packageMeta.version;
-            default:
-              assert(false, 'Unsupported case: ${m.group(1)}');
-              return null;
-          }
-        });
-        if (!_baseHref.endsWith('/')) _baseHref = '${_baseHref}/';
-      } else {
-        _baseHref = config.useBaseHref ? '' : HTMLBASE_PLACEHOLDER;
-      }
+    if (_baseHref != null) {
+      return _baseHref;
     }
+
+    if (documentedWhere == DocumentLocation.remote) {
+      _baseHref = _remoteBaseHref;
+      if (!_baseHref.endsWith('/')) _baseHref = '${_baseHref}/';
+    } else {
+      _baseHref = config.useBaseHref ? '' : HTMLBASE_PLACEHOLDER;
+    }
+
     return _baseHref;
   }
 
+  String get _remoteBaseHref {
+    return config.linkToUrl.replaceAllMapped(_substituteNameVersion, (m) {
+      switch (m.group(1)) {
+        // Return the prerelease tag of the release if a prerelease, or 'stable'
+        // otherwise.  Mostly coded around the Dart SDK's use of dev/stable, but
+        // theoretically applicable elsewhere.
+        case 'b':
+          {
+            var version = Version.parse(packageMeta.version);
+            var tag = 'stable';
+            if (version.isPreRelease) {
+              // `version.preRelease` is a `List<dynamic>` with a mix of
+              // integers and strings.  Given this, handle
+              // "2.8.0-dev.1.0, 2.9.0-1.0.dev", and similar variations.
+              tag = version.preRelease.whereType<String>().first;
+              // Who knows about non-SDK packages, but SDKs must conform to the
+              // known format.
+              assert(packageMeta.isSdk == false || int.tryParse(tag) == null,
+                  'Got an integer as string instead of the expected "dev" tag');
+            }
+            return tag;
+          }
+        case 'n':
+          return name;
+        // The full version string of the package.
+        case 'v':
+          return packageMeta.version;
+        default:
+          assert(false, 'Unsupported case: ${m.group(1)}');
+          return null;
+      }
+    });
+  }
+
+  static final _substituteNameVersion = RegExp(r'%([bnv])%');
+
   @override
   String get href => '$baseHref$filePath';
 

lib/src/model/package_builder.dart

@@ -439,7 +439,7 @@ class PubPackageBuilder implements PackageBuilder {
   }
 
   Future<void> getLibraries(PackageGraph uninitializedPackageGraph) async {
-    DartSdk findSpecialsSdk = sdk;
+    var findSpecialsSdk = sdk;
     if (embedderSdk != null && embedderSdk.urlMappings.isNotEmpty) {
       findSpecialsSdk = embedderSdk;
     }

lib/src/package_config_provider.dart

@@ -8,6 +8,10 @@ import 'dart:io' as io;
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:package_config/package_config.dart' as package_config;
 
+/// A provider of PackageConfig-finding methods.
+///
+/// This provides an abstraction around package_config, which can only work
+/// with the physical file system.
 abstract class PackageConfigProvider {
   Future<package_config.PackageConfig> findPackageConfig(Folder dir);
 }

lib/src/package_meta.dart

@@ -99,9 +99,10 @@ abstract class PackageMeta {
 
   p.Context get pathContext => resourceProvider.pathContext;
 
-  /// Returns true if this represents a 'Dart' SDK.  A package can be part of
-  /// Dart and Flutter at the same time, but if we are part of a Dart SDK
-  /// sdkType should never return null.
+  /// Returns true if this represents a 'Dart' SDK.
+  ///
+  /// A package can be part of Dart and Flutter at the same time, but if we are
+  /// part of a Dart SDK, [sdkType] should never return null.
   bool get isSdk;
 
   /// Returns 'Dart' or 'Flutter' (preferentially, 'Flutter' when the answer is
@@ -160,11 +161,10 @@ abstract class PubPackageMeta extends PackageMeta {
       __sdkDirFilePaths = [];
       if (Platform.isWindows) {
         for (var paths in __sdkDirFilePathsPosix) {
-          var windowsPaths = <String>[];
-          for (var path in paths) {
-            windowsPaths
-                .add(p.joinAll(p.Context(style: p.Style.posix).split(path)));
-          }
+          var windowsPaths = [
+            for (var path in paths)
+              p.joinAll(p.Context(style: p.Style.posix).split(path)),
+          ];
           __sdkDirFilePaths.add(windowsPaths);
         }
       } else {
@@ -176,15 +176,18 @@ abstract class PubPackageMeta extends PackageMeta {
 
   static final _sdkDirParent = <String, Folder>{};
 
-  /// Returns the directory of the SDK if the given directory is inside a Dart
-  /// SDK.  Returns null if the directory isn't a subdirectory of the SDK.
+  /// If [dir] is inside a Dart SDK, returns the directory of the SDK, and `null`
+  /// otherwise.
   static Folder sdkDirParent(Folder dir, ResourceProvider resourceProvider) {
     var pathContext = resourceProvider.pathContext;
     var dirPathCanonical = pathContext.canonicalize(dir.path);
     if (!_sdkDirParent.containsKey(dirPathCanonical)) {
       _sdkDirParent[dirPathCanonical] = null;
       while (dir.exists) {
         if (_sdkDirFilePaths.every((List<String> l) {
+          var path = pathContext.join(dir.path, l.last);
+          print('checking ${dir.path} for $l: does $path exist? '
+              '${resourceProvider.getFile(path).exists}');
           return l.any((f) =>
               resourceProvider.getFile(pathContext.join(dir.path, f)).exists);
         })) {

test/comment_processable_test.dart

@@ -44,7 +44,7 @@ name: foo
       PubPackageMeta.fromFilename,
       PubPackageMeta.fromDir,
       resourceProvider,
-      resourceProvider.getFolder(sdkRoot),
+      resourceProvider.getFolder(resourceProvider.convertPath(sdkRoot)),
     );
     var optionSet = await DartdocOptionSet.fromOptionGenerators(
         'dartdoc', [createDartdocOptions], packageMetaProvider);

test/package_test.dart

@@ -25,33 +25,47 @@ void main() {
 
   void writeSdk() {
     mockSdk = MockSdk(resourceProvider: resourceProvider);
-    sdkFolder = resourceProvider.getFolder(sdkRoot);
-    var pathContext = resourceProvider.pathContext;
-    resourceProvider.getFolder(sdkRoot).create();
-    resourceProvider
-        .getFile(pathContext.join(sdkRoot, 'bin', 'dart'))
-        .writeAsStringSync('');
-    resourceProvider
-        .getFile(pathContext.join(sdkRoot, 'bin', 'pub'))
-        .writeAsStringSync('');
+    for (var l in mockSdk.sdkLibraries) {
+      var p = l.path;
+      resourceProvider
+          .getFile(resourceProvider.pathContext.canonicalize(p))
+          .writeAsStringSync(resourceProvider.getFile(p).readAsStringSync());
+    }
+    sdkFolder = resourceProvider.getFolder(resourceProvider.pathContext
+        .canonicalize(resourceProvider.convertPath(sdkRoot)))
+      ..create();
+    sdkFolder.getChildAssumingFile('version').writeAsStringSync('2.9.0');
+    var sdkBinFolder = sdkFolder.getChildAssumingFolder('bin')..create();
+    sdkBinFolder.getChildAssumingFile('dart').writeAsStringSync('');
+    sdkBinFolder.getChildAssumingFile('pub').writeAsStringSync('');
+
+    var sdkFolderNonCanon = resourceProvider
+        .getFolder(resourceProvider.convertPath(sdkRoot))
+          ..create();
+    var sdkBinFolderNonCanon = sdkFolderNonCanon.getChildAssumingFolder('bin')
+      ..create();
+    sdkBinFolderNonCanon.getChildAssumingFile('dart').writeAsStringSync('');
+    sdkBinFolderNonCanon.getChildAssumingFile('pub').writeAsStringSync('');
   }
 
   void writePackage() {
     var pathContext = resourceProvider.pathContext;
-    var projectFolder = resourceProvider
-        .getFolder(resourceProvider.convertPath('/projects/$packageName'));
+    var projectsFolder = resourceProvider.getFolder(
+        pathContext.canonicalize(resourceProvider.convertPath('/projects')))
+      ..create();
+    var projectFolder = projectsFolder.getChildAssumingFolder(packageName)
+      ..create;
     projectRoot = projectFolder.path;
-    projectFolder.create();
-    resourceProvider
-        .getFile(pathContext.join(projectRoot, 'pubspec.yaml'))
-        .writeAsStringSync('''
+    projectFolder.getChildAssumingFile('pubspec.yaml').writeAsStringSync('''
 name: $packageName
+version: 0.0.1
 ''');
-    resourceProvider
-        .getFile(
-            pathContext.join(projectRoot, '.dart_tool', 'package_config.json'))
+    projectFolder.getChildAssumingFolder('.dart_tool').create();
+    projectFolder
+        .getChildAssumingFolder('.dart_tool')
+        .getChildAssumingFile('package_config.json')
         .writeAsStringSync('');
-    resourceProvider.getFolder(pathContext.join(projectRoot, 'lib')).create();
+    projectFolder.getChildAssumingFolder('lib').create();
     packageConfigProvider.addPackageToConfigFor(
         projectRoot, packageName, Uri.file('$projectRoot/'));
   }