Clean up the semantics of package descriptions.

lib/src/source/hosted.dart

 // Copyright (c) 2012, 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.
 
 library pub.source.hosted;
 
 import 'dart:async';
 import 'dart:io' as io;
 import "dart:convert";
 
 import 'package:http/http.dart' as http;
 import 'package:path/path.dart' as path;
 import 'package:pub_semver/pub_semver.dart';
 
 import '../exceptions.dart';
 import '../http.dart';
 import '../io.dart';
 import '../log.dart' as log;
 import '../package.dart';
 import '../pubspec.dart';
 import '../utils.dart';
 import 'cached.dart';
 
 /// A package source that gets packages from a package hosting site that uses
 /// the same API as pub.dartlang.org.
 class HostedSource extends CachedSource {
+  /// Returns a reference to a hosted package named [name].
+  ///
+  /// If [url] is passed, it's the URL of the pub server from which the package
+  /// should be downloaded. It can be a [Uri] or a [String].
+  static PackageRef refFor(String name, {url}) =>
+      new PackageRef(name, 'hosted', _descriptionFor(name, url));
+
+  /// Returns an ID for a hosted package named [name] at [version].
+  ///
+  /// If [url] is passed, it's the URL of the pub server from which the package
+  /// should be downloaded. It can be a [Uri] or a [String].
+  static PackageId idFor(String name, Version version, {url}) =>
+      new PackageId(name, 'hosted', version, _descriptionFor(name, url));
+
+  /// Returns the description for a hosted package named [name] with the
+  /// given package server [url].
+  static _descriptionFor(String name, [url]) {
+    if (url == null) return name;
+
+    if (url is! String && url is! Uri) {
+      throw new ArgumentError.value(url, 'url', 'must be a Uri or a String.');
+    }
+
+    return {'name': name, 'url': url.toString()};
+  }
+
   final name = "hosted";
   final hasMultipleVersions = true;
 
   /// Gets the default URL for the package server for hosted dependencies.
   static String get defaultUrl {
     var url = io.Platform.environment["PUB_HOSTED_URL"];
     if (url != null) return url;
 
     return "https://pub.dartlang.org";
   }
@@ skipping 12 matching lines @@
     } catch (error, stackTrace) {
       var parsed = _parseDescription(ref.description);
       _throwFriendlyError(error, stackTrace, parsed.first, parsed.last);
     }
 
     var doc = JSON.decode(body);
     return doc['versions'].map((map) {
       var pubspec = new Pubspec.fromMap(
           map['pubspec'], systemCache.sources,
           expectedName: ref.name, location: url);
-      var id = ref.atVersion(pubspec.version);
+      var id = idFor(ref.name, pubspec.version);
       memoizePubspec(id, pubspec);
 
       return id;
     }).toList();
   }
 
   /// Downloads and parses the pubspec for a specific version of a package that
   /// is available from the site.
   Future<Pubspec> describeUncached(PackageId id) async {
     // Request it from the server.
@@ skipping 41 matching lines @@
   String packageName(description) => _parseDescription(description).first;
 
   bool descriptionsEqual(description1, description2) =>
       _parseDescription(description1) == _parseDescription(description2);
 
   /// Ensures that [description] is a valid hosted package description.
   ///
   /// There are two valid formats. A plain string refers to a package with the
   /// given name from the default host, while a map with keys "name" and "url"
   /// refers to a package with the given name from the host at the given URL.
-  dynamic parseDescription(String containingPath, description,
-                           {bool fromLockFile: false}) {
+  PackageRef parseRef(String name, description, {String containingPath}) {
     _parseDescription(description);
-    return description;
+    return new PackageRef(name, this.name, description);
+  }
+
+  PackageId parseId(String name, Version version, description) {
+    _parseDescription(description);
+    return new PackageId(name, this.name, version, description);
   }
 
   /// Re-downloads all packages that have been previously downloaded into the
   /// system cache from any server.
   Future<Pair<List<PackageId>, List<PackageId>>> repairCachedPackages() async {
     if (!dirExists(systemCacheRoot)) return new Pair([], []);
 
     var successes = [];
     var failures = [];
 
     for (var serverDir in listDir(systemCacheRoot)) {
       var url = _directoryToUrl(path.basename(serverDir));
       var packages = _getCachedPackagesInDirectory(path.basename(serverDir));
       packages.sort(Package.orderByNameAndVersion);
 
       for (var package in packages) {
-        var id = new PackageId(package.name, this.name, package.version, null);
+        var id = idFor(package.name, package.version);
 
         try {
           await _download(url, package.name, package.version, package.dir);
           successes.add(id);
         } catch (error, stackTrace) {
           failures.add(id);
           var message = "Failed to repair ${log.bold(package.name)} "
               "${package.version}";
           if (url != defaultUrl) message += " from $url";
           log.error("$message. Error:\n$error");
@@ skipping 82 matching lines @@
     log.io("Finding versions of ${ref.name} in "
         "$systemCacheRoot/${_urlToDirectory(server)}");
 
     var dir = path.join(systemCacheRoot, _urlToDirectory(server));
 
     var versions;
     if (dirExists(dir)) {
       versions = await listDir(dir).map((entry) {
         var components = path.basename(entry).split("-");
         if (components.first != ref.name) return null;
-        return ref.atVersion(new Version.parse(components.last));
+        return HostedSource.idFor(ref.name, new Version.parse(components.last));
       }).where((id) => id != null).toList();
     } else {
       versions = [];
     }
 
     // If there are no versions in the cache, report a clearer error.
     if (versions.isEmpty) {
       throw new PackageNotFoundException(
           "Could not find package ${ref.name} in cache.");
     }
@@ skipping 104 matching lines @@
   var name = description["name"];
   if (name is! String) {
     throw new FormatException("The 'name' key must have a string value.");
   }
 
   var url = description["url"];
   if (url == null) url = HostedSource.defaultUrl;
 
   return new Pair<String, String>(name, url);
 }