Dynamically reduce dartdoc timeout with total time budget option.

CHANGELOG.md

@@ -4,6 +4,7 @@
   directory used for the analysis (helps switching different analyzer SDKs).
 - `ToolEnvironment.create()` takes `pubHostedUrl` as `PackageAnalyzer.create()`
   was removed.
+- `InspectOptions.totalTimeBudget` to allow the dynamic reduction of `dartdocTimeout`.
 
 **BREAKING CHANGES**
 

lib/src/package_analyzer.dart

@@ -28,12 +28,14 @@ import 'utils.dart';
 class InspectOptions {
   final String? pubHostedUrl;
   final String? dartdocOutputDir;
+  final Duration? totalTimeBudget;
   final Duration? dartdocTimeout;
   final int? lineLength;
 
   InspectOptions({
     this.pubHostedUrl,
     this.dartdocOutputDir,
+    this.totalTimeBudget,
     this.dartdocTimeout,
     this.lineLength,
   });

lib/src/package_context.dart

@@ -92,17 +92,23 @@ class PackageContext {
   final String packageDir;
   final errors = <String>[];
   final urlProblems = <String, String>{};
+  final _stopwatch = Stopwatch();
 
   Pubspec? _pubspec;
   List<CodeProblem>? _codeProblems;
 
   PackageContext({
     required this.sharedContext,
     required this.packageDir,
-  });
+  }) {
+    _stopwatch.start();
+  }
 
   ToolEnvironment get toolEnvironment => sharedContext.toolEnvironment;
   InspectOptions get options => sharedContext.options;
+  Duration? remainingTimeBudget() => options.totalTimeBudget == null
+      ? null
+      : (options.totalTimeBudget! - _stopwatch.elapsed);
 
   late final Version currentSdkVersion =
       Version.parse(toolEnvironment.runtimeInfo.sdkVersion);
@@ -235,7 +241,11 @@ class PackageContext {
       return DartdocResult.skipped();
     }
     if (await resolveDependencies()) {
-      final timeout = options.dartdocTimeout ?? const Duration(minutes: 5);
+      var timeout = options.dartdocTimeout ?? const Duration(minutes: 5);
+      final rtb = remainingTimeBudget();
+      if (rtb != null && rtb < timeout) {
+        timeout = rtb;
+      }
       await normalizeDartdocOptionsYaml(packageDir);
       try {
         final pr = await toolEnvironment.dartdoc(