Update all (approximately) i/o operations to use ResourceProvider (#2315)

All i/o operations now pass through a ResourceProvider, an abstraction which allows disk-free testing. In this change, almost all ResourceProviders used are the PhysicalResourceProvider; no tests are converted from being filesystem-dependent to using MemoryResourceProvider.

dartdoc uses the filesystem extensively, so this change is large. Often top-level or static elements become more complicated, depending on a ResourceProvider variable.

Some extra dart:io functionality not found in ResourceProvider is added via an extension, ResourceProviderExtensions.

Many classes have a new ResourceProvider resourceProvider field: DartdocFileWriter, SnapshotCache, DartToolDefinition, ToolConfiguration, DartdocOption, PackageMetaProvider, PackageMeta, ToolTempFileTracker,

Each of SnapshotCache and ToolTempFileTracker has a static instance field which took no arguments; now that they need a ResourceProvider, it was unwieldy to pass a ResourceProvider to get the instance each time, so a new method, createInstance creates the instance.

Author: srawlins

bin/dartdoc.dart

@@ -17,7 +17,7 @@ Future<void> main(List<String> arguments) async {
     // There was an error while parsing options.
     return;
   }
-  final packageBuilder = PubPackageBuilder(config);
+  final packageBuilder = PubPackageBuilder(config, pubPackageMetaProvider);
   final dartdoc = config.generateDocs
       ? await Dartdoc.fromContext(config, packageBuilder)
       : await Dartdoc.withEmptyGenerator(config, packageBuilder);

lib/dartdoc.dart

@@ -10,8 +10,9 @@ library dartdoc;
 
 import 'dart:async';
 import 'dart:convert';
-import 'dart:io';
+import 'dart:io' show exitCode, stderr;
 
+import 'package:analyzer/file_system/file_system.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/generator/empty_generator.dart';
 import 'package:dartdoc/src/generator/generator.dart';
@@ -41,17 +42,19 @@ const String dartdocVersion = packageVersion;
 /// Helper class that consolidates option contexts for instantiating generators.
 class DartdocGeneratorOptionContext extends DartdocOptionContext
     with GeneratorContext {
-  DartdocGeneratorOptionContext(DartdocOptionSet optionSet, Directory dir)
-      : super(optionSet, dir);
+  DartdocGeneratorOptionContext(
+      DartdocOptionSet optionSet, Folder dir, ResourceProvider resourceProvider)
+      : super(optionSet, dir, resourceProvider);
 }
 
 class DartdocFileWriter implements FileWriter {
   final String outputDir;
+  ResourceProvider resourceProvider;
   final Map<String, Warnable> _fileElementMap = {};
   @override
   final Set<String> writtenFiles = {};
 
-  DartdocFileWriter(this.outputDir);
+  DartdocFileWriter(this.outputDir, this.resourceProvider);
 
   @override
   void write(String filePath, Object content,
@@ -73,10 +76,11 @@ class DartdocFileWriter implements FileWriter {
     }
     _fileElementMap[outFile] = element;
 
-    var file = File(path.join(outputDir, outFile));
+    var file = resourceProvider
+        .getFile(resourceProvider.pathContext.join(outputDir, outFile));
     var parent = file.parent;
-    if (!parent.existsSync()) {
-      parent.createSync(recursive: true);
+    if (!parent.exists) {
+      parent.create();
     }
 
     if (content is String) {
@@ -100,14 +104,16 @@ class Dartdoc {
   final PackageBuilder packageBuilder;
   final DartdocOptionContext config;
   final Set<String> writtenFiles = {};
-  Directory outputDir;
+  Folder outputDir;
 
   // Fires when the self checks make progress.
   final StreamController<String> _onCheckProgress =
       StreamController(sync: true);
 
   Dartdoc._(this.config, this.generator, this.packageBuilder) {
-    outputDir = Directory(config.output)..createSync(recursive: true);
+    outputDir = config.resourceProvider
+        .getFolder(config.resourceProvider.pathContext.absolute(config.output))
+          ..create();
   }
 
   /// An asynchronous factory method that builds Dartdoc's file writers
@@ -182,9 +188,9 @@ class Dartdoc {
     final generator = this.generator;
     if (generator != null) {
       // Create the out directory.
-      if (!outputDir.existsSync()) outputDir.createSync(recursive: true);
+      if (!outputDir.exists) outputDir.create();
 
-      var writer = DartdocFileWriter(outputDir.path);
+      var writer = DartdocFileWriter(outputDir.path, config.resourceProvider);
       await generator.generate(packageGraph, writer);
 
       writtenFiles.addAll(writer.writtenFiles);
@@ -225,15 +231,16 @@ class Dartdoc {
         throw DartdocFailure(
             'dartdoc encountered $errorCount errors while processing.');
       }
-      logInfo(
-          'Success! Docs generated into ${dartdocResults.outDir.absolute.path}');
+      var outDirPath = config.resourceProvider.pathContext
+          .absolute(dartdocResults.outDir.path);
+      logInfo('Success! Docs generated into $outDirPath');
       return dartdocResults;
     } finally {
       // Clear out any cached tool snapshots and temporary directories.
       // ignore: unawaited_futures
-      SnapshotCache.instance.dispose();
+      SnapshotCache.instance?.dispose();
       // ignore: unawaited_futures
-      ToolTempFileTracker.instance.dispose();
+      ToolTempFileTracker.instance?.dispose();
     }
   }
 
@@ -289,35 +296,43 @@ class Dartdoc {
     var staticAssets = path.joinAll([normalOrigin, 'static-assets', '']);
     var indexJson = path.joinAll([normalOrigin, 'index.json']);
     var foundIndexJson = false;
-    for (var f in Directory(normalOrigin).listSync(recursive: true)) {
-      if (f is Directory) {
-        continue;
-      }
-      var fullPath = path.normalize(f.path);
-      if (fullPath.startsWith(staticAssets)) {
-        continue;
-      }
-      if (fullPath == indexJson) {
-        foundIndexJson = true;
-        _onCheckProgress.add(fullPath);
-        continue;
-      }
-      if (visited.contains(fullPath)) continue;
-      var relativeFullPath = path.relative(fullPath, from: normalOrigin);
-      if (!writtenFiles.contains(relativeFullPath)) {
-        // This isn't a file we wrote (this time); don't claim we did.
-        _warn(packageGraph, PackageWarning.unknownFile, fullPath, normalOrigin);
-      } else {
-        // Error messages are orphaned by design and do not appear in the search
-        // index.
-        if (<String>['__404error.html', 'categories.json'].contains(fullPath)) {
-          _warn(packageGraph, PackageWarning.orphanedFile, fullPath,
-              normalOrigin);
+
+    void checkDirectory(Folder dir) {
+      for (var f in dir.getChildren()) {
+        if (f is Folder) {
+          checkDirectory(f);
+          continue;
+        }
+        var fullPath = path.normalize(f.path);
+        if (fullPath.startsWith(staticAssets)) {
+          continue;
         }
+        if (path.equals(fullPath, indexJson)) {
+          foundIndexJson = true;
+          _onCheckProgress.add(fullPath);
+          continue;
+        }
+        if (visited.contains(fullPath)) continue;
+        var relativeFullPath = path.relative(fullPath, from: normalOrigin);
+        if (!writtenFiles.contains(relativeFullPath)) {
+          // This isn't a file we wrote (this time); don't claim we did.
+          _warn(
+              packageGraph, PackageWarning.unknownFile, fullPath, normalOrigin);
+        } else {
+          // Error messages are orphaned by design and do not appear in the search
+          // index.
+          if (<String>['__404error.html', 'categories.json']
+              .contains(fullPath)) {
+            _warn(packageGraph, PackageWarning.orphanedFile, fullPath,
+                normalOrigin);
+          }
+        }
+        _onCheckProgress.add(fullPath);
       }
-      _onCheckProgress.add(fullPath);
     }
 
+    checkDirectory(config.resourceProvider.getFolder(normalOrigin));
+
     if (!foundIndexJson) {
       _warn(packageGraph, PackageWarning.brokenLink, indexJson, normalOrigin);
       _onCheckProgress.add(indexJson);
@@ -327,8 +342,8 @@ class Dartdoc {
   // This is extracted to save memory during the check; be careful not to hang
   // on to anything referencing the full file and doc tree.
   Tuple2<Iterable<String>, String> _getStringLinksAndHref(String fullPath) {
-    var file = File('$fullPath');
-    if (!file.existsSync()) {
+    var file = config.resourceProvider.getFile('$fullPath');
+    if (!file.exists) {
       return null;
     }
     // TODO(srawlins): It is possible that instantiating an HtmlParser using
@@ -353,8 +368,8 @@ class Dartdoc {
       PackageGraph packageGraph, String origin, Set<String> visited) {
     var fullPath = path.joinAll([origin, 'index.json']);
     var indexPath = path.joinAll([origin, 'index.html']);
-    var file = File('$fullPath');
-    if (!file.existsSync()) {
+    var file = config.resourceProvider.getFile('$fullPath');
+    if (!file.exists) {
       return null;
     }
     var decoder = JsonDecoder();
@@ -519,7 +534,7 @@ class DartdocFailure {
 class DartdocResults {
   final PackageMeta packageMeta;
   final PackageGraph packageGraph;
-  final Directory outDir;
+  final Folder outDir;
 
   DartdocResults(this.packageMeta, this.packageGraph, this.outDir);
 }

lib/options.dart

@@ -1,29 +1,34 @@
 import 'dart:async';
-import 'dart:io';
+import 'dart:io' show stderr, exitCode;
 
+import 'package:analyzer/file_system/file_system.dart';
 import 'package:args/args.dart';
 import 'package:dartdoc/dartdoc.dart';
 import 'package:dartdoc/src/logging.dart';
 
 class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
     with LoggingContext {
-  DartdocProgramOptionContext(DartdocOptionSet optionSet, Directory dir)
-      : super(optionSet, dir);
+  DartdocProgramOptionContext(
+      DartdocOptionSet optionSet, Folder dir, ResourceProvider resourceProvider)
+      : super(optionSet, dir, resourceProvider);
 
   bool get generateDocs => optionSet['generateDocs'].valueAt(context);
   bool get help => optionSet['help'].valueAt(context);
   bool get version => optionSet['version'].valueAt(context);
 }
 
-Future<List<DartdocOption<bool>>> createDartdocProgramOptions() async {
+Future<List<DartdocOption<bool>>> createDartdocProgramOptions(
+    PackageMetaProvider packageMetaProvider) async {
+  var resourceProvider = packageMetaProvider.resourceProvider;
   return [
-    DartdocOptionArgOnly<bool>('generateDocs', true,
+    DartdocOptionArgOnly<bool>('generateDocs', true, resourceProvider,
         help:
-            'Generate docs into the output directory (or only display warnings if false).',
+            'Generate docs into the output directory (or only display warnings '
+            'if false).',
         negatable: true),
-    DartdocOptionArgOnly<bool>('help', false,
+    DartdocOptionArgOnly<bool>('help', false, resourceProvider,
         abbr: 'h', help: 'Show command help.', negatable: false),
-    DartdocOptionArgOnly<bool>('version', false,
+    DartdocOptionArgOnly<bool>('version', false, resourceProvider,
         help: 'Display the version for $programName.', negatable: false),
   ];
 }
@@ -33,13 +38,16 @@ Future<DartdocProgramOptionContext> parseOptions(
   List<String> arguments, {
   OptionGenerator additionalOptions,
 }) async {
-  var optionSet = await DartdocOptionSet.fromOptionGenerators('dartdoc', [
-    () => createDartdocOptions(packageMetaProvider),
-    createDartdocProgramOptions,
-    createLoggingOptions,
-    createGeneratorOptions,
-    if (additionalOptions != null) additionalOptions,
-  ]);
+  var optionSet = await DartdocOptionSet.fromOptionGenerators(
+      'dartdoc',
+      [
+        createDartdocOptions,
+        createDartdocProgramOptions,
+        createLoggingOptions,
+        createGeneratorOptions,
+        if (additionalOptions != null) additionalOptions,
+      ],
+      packageMetaProvider);
 
   try {
     optionSet.parseArguments(arguments);
@@ -51,20 +59,21 @@ Future<DartdocProgramOptionContext> parseOptions(
     exitCode = 64;
     return null;
   }
-  if (optionSet['help'].valueAt(Directory.current)) {
+  if (optionSet['help'].valueAtCurrent()) {
     _printHelp(optionSet.argParser);
     exitCode = 0;
     return null;
   }
-  if (optionSet['version'].valueAt(Directory.current)) {
+  if (optionSet['version'].valueAtCurrent()) {
     _printVersion(optionSet.argParser);
     exitCode = 0;
     return null;
   }
 
   DartdocProgramOptionContext config;
   try {
-    config = DartdocProgramOptionContext(optionSet, null);
+    config = DartdocProgramOptionContext(
+        optionSet, null, packageMetaProvider.resourceProvider);
   } on DartdocOptionError catch (e) {
     stderr.writeln(' fatal error: ${e.message}');
     stderr.writeln('');