Add implementations of the front end FileSystem API.

pkg/front_end/lib/file_system.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 front_end.file_system;
 
 import 'dart:async';
 
 import 'package:path/path.dart' as path;
 
@@ skipping 13 matching lines @@
   ///
   /// Uses of `..` and `.` in path are normalized before returning (so, for
   /// example, `entityForPath('./foo')` and `entityForPath('foo')` are
   /// equivalent).  Relative paths are also converted to absolute paths.
   ///
   /// Does not check whether a file or folder exists at the given location.
   FileSystemEntity entityForPath(String path);
 
   /// Returns a [FileSystemEntity] corresponding to the given [uri].
   ///
-  /// Uses of `..` and `.` in the URI are normalized before returning.  Relative
-  /// paths are also converted to absolute paths.
+  /// Uses of `..` and `.` in the URI are normalized before returning.
   ///
-  /// If [uri] is not a `file:` URI, an [Error] will be thrown.
+  /// If [uri] is not an absolute `file:` URI, an [Error] will be thrown.
   ///
   /// Does not check whether a file or folder exists at the given location.
   FileSystemEntity entityForUri(Uri uri);
 }
 
 /// Abstract representation of a file system entity that may or may not exist.
 ///
+/// Instances of this class have suitable implementations of equality tests and
+/// hashCode.
+///
 /// Not intended to be implemented or extended by clients.
 abstract class FileSystemEntity {
   /// Returns the absolute normalized path represented by this file system
   /// entity.
   ///
   /// Note: if the [FileSystemEntity] was created using
   /// [FileSystem.entityForPath], this is not necessarily the same as the path
   /// that was used to create the object, since the path might have been
   /// normalized.
   String get path;
 
   /// Attempts to access this file system entity as a file and read its contents
   /// as raw bytes.
   ///
   /// If an error occurs while attempting to read the file (e.g. because no such
   /// file exists, or the entity is a directory), the future is completed with
   /// an [Exception].
   Future<List<int>> readAsBytes();
 
   /// Attempts to access this file system entity as a file and read its contents
   /// as a string.
   ///
   /// The file is assumed to be UTF-8 encoded.
   ///
   /// If an error occurs while attempting to read the file (e.g. because no such
-  /// file exists, or the entity is a directory), the future is completed with
-  /// an [Exception].
+  /// file exists, the entity is a directory, or the file is not valid UTF-8),
+  /// the future is completed with an [Exception].
   Future<String> readAsString();
 }