Refactorings for TranslateUri and its tests.

pkg/front_end/lib/src/fasta/translate_uri.dart

 // Copyright (c) 2016, 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 fasta.translate_uri;
 
 import 'dart:async' show Future;
-
 import 'dart:convert' show JSON;
 
 import 'package:front_end/file_system.dart'
     show FileSystem, FileSystemException;
-
 import 'package:package_config/packages_file.dart' as packages_file show parse;
 
 import 'deprecated_problems.dart' show deprecated_inputError;
 
+/// Instances of [TranslateUri] translate absolute `dart` and `package` URIs
+/// into corresponding `file` URIs.

[Siggi Cherem (dart-lang), 2017/07/11 21:56:02]

Just looking at some other CL made me think that I'm not sure if can say that
"translated" Uri is guaranteed to be a `file:` Uri.

For example, with the multi-root option and when using custom-uris in unit
tests, we might get a non file:* uri.

One option is to say: 

Instances of [TranslateUri] translate absolute `dart` and `package` URIs into
corresponding file-system Uris". The translated Uri is typically a `file:` Uri,
but may use a different scheme if the compiler is invoked with the `multiRoot`
option or in unit tests that use a custom file system.

[scheglov, 2017/07/11 23:28:31]

I replaced `file` with just "file" to underscore that it is not literally
file:// URIs.

 class TranslateUri {
-  final Map<String, Uri> packages;
+  /// Mapping from Dart library names (e.g. `math`) to `file` URIs.
   final Map<String, Uri> dartLibraries;
 
   // TODO(ahe): We probably want this to be `Map<String, Uri>`, that is, just
   // one patch library (with parts).
-  final Map<String, List<Uri>> patches;
+  /// Mapping from Dart library names to the `file` URIs of patches to apply.
+  final Map<String, List<Uri>> dartPatches;
 
-  TranslateUri(this.packages, this.dartLibraries, this.patches);
+  /// Mapping from package names (e.g. `path` or `angular`) to the `file` URIs.
+  final Map<String, Uri> packages;
 
+  TranslateUri(this.dartLibraries, this.dartPatches, this.packages);
+
+  /// Returns true if [uri] is private to the platform libraries (and thus not
+  /// accessible from user code).
+  bool isPlatformImplementation(Uri uri) {
+    if (uri.scheme != "dart") return false;
+    String path = uri.path;
+    return dartLibraries[path] == null || path.startsWith("_");
+  }
+
+  /// If the given [uri] is a `file` or `package` URI, return the corresponding
+  /// `file` URI (possibly `null` if there is no corresponding `file` URI);
+  /// otherwise (e.g. when the [uri] is already a `file` URI) return `null`.
+  /// This is the URIs only transformation, there is no guarantee that the
+  /// corresponding file exists.
   Uri translate(Uri uri) {
-    if (uri.scheme == "dart") return translateDartUri(uri);
-    if (uri.scheme == "package") return translatePackageUri(uri);
+    if (uri.scheme == "dart") return _translateDartUri(uri);
+    if (uri.scheme == "package") return _translatePackageUri(uri);
     return null;
   }
 
-  Uri translateDartUri(Uri uri) {
+  /// Return the file URI that corresponds to the given `dart` URI, or `null`
+  /// if there is no corresponding Dart library registered.
+  Uri _translateDartUri(Uri uri) {
     if (!uri.isScheme('dart')) return null;
     String path = uri.path;
 
     int index = path.indexOf('/');
     if (index == -1) return dartLibraries[path];
 
     String libraryName = path.substring(0, index);
     String relativePath = path.substring(index + 1);
     Uri libraryFileUri = dartLibraries[libraryName];
     return libraryFileUri?.resolve(relativePath);
   }
 
-  Uri translatePackageUri(Uri uri) {
+  /// Return the file URI that corresponds to the given `package` URI, or `null`
+  /// if the `package` [uri] format is invalid, or there is no corresponding
+  /// package registered.
+  Uri _translatePackageUri(Uri uri) {
     int index = uri.path.indexOf("/");
     if (index == -1) return null;
     String name = uri.path.substring(0, index);
     String path = uri.path.substring(index + 1);
     Uri root = packages[name];
     if (root == null) return null;
     return root.resolve(path);
   }
 
-  /// Returns true if [uri] is private to the platform libraries (and thus not
-  /// accessible from user code).
-  bool isPlatformImplementation(Uri uri) {
-    if (uri.scheme != "dart") return false;
-    String path = uri.path;
-    return dartLibraries[path] == null || path.startsWith("_");
-  }
-
   static Future<TranslateUri> parse(FileSystem fileSystem, Uri sdk,
       {Uri packages}) async {
     Uri librariesJson = sdk?.resolve("lib/libraries.json");
 
     // TODO(ahe): Provide a value for this file.
     Uri patches = null;
 
     packages ??= Uri.base.resolve(".packages");
 
     List<int> bytes;
     try {
       bytes = await fileSystem.entityForUri(packages).readAsBytes();
     } on FileSystemException catch (e) {
       deprecated_inputError(packages, -1, e.message);
     }
 
     Map<String, Uri> parsedPackages;
     try {
       parsedPackages = packages_file.parse(bytes, packages);
     } on FormatException catch (e) {
       return deprecated_inputError(packages, e.offset, e.message);
     }
-    return new TranslateUri(
-        parsedPackages,
-        await computeLibraries(fileSystem, librariesJson),
-        await computePatches(fileSystem, patches));
+
+    var dartLibraries = await computeDartLibraries(fileSystem, librariesJson);
+    return new TranslateUri(dartLibraries,
+        await computeDartPatches(fileSystem, patches), parsedPackages);
   }
 }
 
-Future<Map<String, Uri>> computeLibraries(
+/// Read the JSON file with defined SDK libraries from the given [uri] in the
+/// [fileSystem] and return the mapping from parsed Dart library names (e.g.
+/// `math`) to `file` URIs.
+Future<Map<String, Uri>> computeDartLibraries(
     FileSystem fileSystem, Uri uri) async {
   if (uri == null) return const <String, Uri>{};
   Map<String, String> libraries = JSON
       .decode(await fileSystem.entityForUri(uri).readAsString())["libraries"];
   Map<String, Uri> result = <String, Uri>{};
   libraries.forEach((String name, String path) {
     result[name] = uri.resolveUri(new Uri.file(path));
   });
   return result;
 }
 
-Future<Map<String, List<Uri>>> computePatches(
+Future<Map<String, List<Uri>>> computeDartPatches(
     FileSystem fileSystem, Uri uri) async {
   // TODO(ahe): Read patch information.
   return const <String, List<Uri>>{};
 }