[tool] Add a flag to skip cleanup (#4357)

It can be useful in debugging snippet setup to look at the extraction output, but the tool cleans that up automatically. Running the extraction manually is complicated due to the on-the-fly pubspec modifications, so this adds a `--no-cleanup` flag that can be used to skip the deletion of the extraction output, and instead log its location to the terminal.

Author: stuartmorgan-g

script/tool/lib/src/update_excerpts_command.dart

@@ -6,6 +6,7 @@ import 'dart:io' as io;
 
 import 'package:file/file.dart';
 import 'package:git/git.dart';
+import 'package:meta/meta.dart';
 import 'package:platform/platform.dart';
 import 'package:yaml/yaml.dart';
 import 'package:yaml_edit/yaml_edit.dart';
@@ -30,18 +31,24 @@ class UpdateExcerptsCommand extends PackageLoopingCommand {
           gitDir: gitDir,
         ) {
     argParser.addFlag(_failOnChangeFlag, hide: true);
+    argParser.addFlag(_noCleanupFlag,
+        help: 'Skips the step of cleaning up the excerpt extraction output. '
+            'This can be useful when debugging extraction or checking paths to '
+            'reference in snippets.');
   }
 
   static const String _failOnChangeFlag = 'fail-on-change';
+  static const String _noCleanupFlag = 'no-cleanup';
 
   static const String _buildRunnerConfigName = 'excerpt';
   // The name of the build_runner configuration file that will be in an example
   // directory if the package is set up to use `code-excerpt`.
   static const String _buildRunnerConfigFile =
       'build.$_buildRunnerConfigName.yaml';
 
-  // The relative directory path to put the extracted excerpt yaml files.
-  static const String _excerptOutputDir = 'excerpts';
+  /// The relative directory path to put the extracted excerpt yaml files.
+  @visibleForTesting
+  static const String excerptOutputDir = 'excerpts';
 
   // The filename to store the pre-modification copy of the pubspec.
   static const String _originalPubspecFilename =
@@ -97,9 +104,16 @@ class UpdateExcerptsCommand extends PackageLoopingCommand {
         // Clean up the pubspec changes and extracted excerpts directory.
         _undoPubspecChanges(example);
         final Directory excerptDirectory =
-            example.directory.childDirectory(_excerptOutputDir);
+            example.directory.childDirectory(excerptOutputDir);
         if (excerptDirectory.existsSync()) {
-          excerptDirectory.deleteSync(recursive: true);
+          if (getBoolArg(_noCleanupFlag)) {
+            final String relativeDir =
+                getRelativePosixPath(excerptDirectory, from: package.directory);
+            print(
+                '\n\nSKIPPING CLEANUP: Extraction output is in $relativeDir/');
+          } else {
+            excerptDirectory.deleteSync(recursive: true);
+          }
         }
       }
     }
@@ -134,7 +148,7 @@ class UpdateExcerptsCommand extends PackageLoopingCommand {
           '--config',
           _buildRunnerConfigName,
           '--output',
-          _excerptOutputDir,
+          excerptOutputDir,
           '--delete-conflicting-outputs',
         ],
         workingDir: example.directory);

script/tool/test/update_excerpts_command_test.dart

@@ -58,7 +58,7 @@ void main() {
                 '--config',
                 'excerpt',
                 '--output',
-                'excerpts',
+                UpdateExcerptsCommand.excerptOutputDir,
                 '--delete-conflicting-outputs',
               ],
               example.path),
@@ -85,7 +85,7 @@ void main() {
                 '--config',
                 'excerpt',
                 '--output',
-                'excerpts',
+                UpdateExcerptsCommand.excerptOutputDir,
                 '--delete-conflicting-outputs',
               ],
               example.path),
@@ -129,7 +129,7 @@ void main() {
                 '--config',
                 'excerpt',
                 '--output',
-                'excerpts',
+                UpdateExcerptsCommand.excerptOutputDir,
                 '--delete-conflicting-outputs',
               ],
               example.path),
@@ -174,7 +174,7 @@ void main() {
                 '--config',
                 'excerpt',
                 '--output',
-                'excerpts',
+                UpdateExcerptsCommand.excerptOutputDir,
                 '--delete-conflicting-outputs',
               ],
               example.path),
@@ -416,4 +416,52 @@ void main() {
           contains('Unable to determine local file state'),
         ]));
   });
+
+  test('cleans up excerpt output by default', () async {
+    final RepositoryPackage package = createFakePackage(
+        'a_package', packagesDir,
+        extraFiles: <String>[kReadmeExcerptConfigPath]);
+    // Simulate the creation of the output directory.
+    final Directory excerptOutputDir = package
+        .getExamples()
+        .first
+        .directory
+        .childDirectory(UpdateExcerptsCommand.excerptOutputDir);
+    excerptOutputDir.createSync(recursive: true);
+
+    const String changedFilePath = 'packages/a_plugin/linux/CMakeLists.txt';
+    processRunner.mockProcessesForExecutable['git'] = <FakeProcessInfo>[
+      FakeProcessInfo(MockProcess(stdout: changedFilePath)),
+    ];
+
+    await runCapturingPrint(runner, <String>['update-excerpts']);
+
+    expect(excerptOutputDir.existsSync(), false);
+  });
+
+  test('cleans up excerpt output by default', () async {
+    final RepositoryPackage package = createFakePackage(
+        'a_package', packagesDir,
+        extraFiles: <String>[kReadmeExcerptConfigPath]);
+    // Simulate the creation of the output directory.
+    const String outputDirName = UpdateExcerptsCommand.excerptOutputDir;
+    final Directory excerptOutputDir =
+        package.getExamples().first.directory.childDirectory(outputDirName);
+    excerptOutputDir.createSync(recursive: true);
+
+    const String changedFilePath = 'packages/a_plugin/linux/CMakeLists.txt';
+    processRunner.mockProcessesForExecutable['git'] = <FakeProcessInfo>[
+      FakeProcessInfo(MockProcess(stdout: changedFilePath)),
+    ];
+
+    final List<String> output = await runCapturingPrint(
+        runner, <String>['update-excerpts', '--no-cleanup']);
+
+    expect(
+        output,
+        containsAllInOrder(<Matcher>[
+          contains('Extraction output is in example/$outputDirName/'),
+        ]));
+    expect(excerptOutputDir.existsSync(), true);
+  });
 }