From 2760d2547aaed9474292879e6f51c58452267c20 Mon Sep 17 00:00:00 2001
From: Sam Rawlins <srawlins@google.com>
Date: Wed, 28 Feb 2024 16:59:11 -0800
Subject: [PATCH] Deprecate the 'include-externals' option. (#3694)

I cannot see that this is used anywhere. We also have no tests for it. The
documentation is minimal. It was added 8 years ago! How time flies!

I suspect this was put in place for Flutter, and Flutter switched to using
the newer `--auto-include-dependencies` option.
---
 lib/src/dartdoc.dart               |  8 ++++++++
 lib/src/model/package_builder.dart | 19 +++++++++++++++++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/lib/src/dartdoc.dart b/lib/src/dartdoc.dart
index bb6e3983e2..a2e4d92ff5 100644
--- a/lib/src/dartdoc.dart
+++ b/lib/src/dartdoc.dart
@@ -188,6 +188,14 @@ class Dartdoc {
     runtimeStats.startPerfTask('buildPackageGraph');
     var packageGraph = await packageBuilder.buildPackageGraph();
     runtimeStats.endPerfTask();
+    if (packageBuilder.includeExternalsWasSpecified) {
+      packageGraph.defaultPackage.warn(
+        PackageWarning.deprecated,
+        message:
+            "The '--include-externals' option is deprecated, and will soon be "
+            'removed.',
+      );
+    }
     var libs = packageGraph.libraryCount;
     logInfo("Initialized dartdoc with $libs librar${libs == 1 ? 'y' : 'ies'}");
 
diff --git a/lib/src/model/package_builder.dart b/lib/src/model/package_builder.dart
index 37851e5689..5c2b2f3818 100644
--- a/lib/src/model/package_builder.dart
+++ b/lib/src/model/package_builder.dart
@@ -39,6 +39,10 @@ abstract class PackageBuilder {
   Future<PackageGraph> buildPackageGraph();
 
   Future<void> dispose();
+
+  /// The `include-external` option is deprecated, so we track whether it was
+  /// used, to report it.
+  bool get includeExternalsWasSpecified;
 }
 
 /// A package builder that understands pub package format.
@@ -283,7 +287,11 @@ class PubPackageBuilder implements PackageBuilder {
       }
       files.addAll(newFiles);
       if (!addingSpecials) {
-        files.addAll(_includedExternalsFrom(newFiles));
+        var externals = _includedExternalsFrom(newFiles);
+        if (externals.isNotEmpty) {
+          includeExternalsWasSpecified = true;
+        }
+        files.addAll(externals);
       }
 
       var packages = _packageMetasForFiles(files.difference(_knownParts));
@@ -437,7 +445,11 @@ class PubPackageBuilder implements PackageBuilder {
             includeDependencies: _config.autoIncludeDependencies,
             filterExcludes: true,
           ).toList();
-    files = [...files, ..._includedExternalsFrom(files)];
+    var externals = _includedExternalsFrom(files);
+    if (externals.isNotEmpty) {
+      includeExternalsWasSpecified = true;
+    }
+    files = [...files, ...externals];
     return {
       ...files
           .map((s) => _pathContext.absolute(_resourceProvider.getFile(s).path)),
@@ -445,6 +457,9 @@ class PubPackageBuilder implements PackageBuilder {
     };
   }
 
+  @override
+  bool includeExternalsWasSpecified = false;
+
   Iterable<String> get _embedderSdkFiles => [
         for (var dartUri in _embedderSdkUris)
           _pathContext.absolute(_resourceProvider