Added --preserveWatchOutput flag (#21303)

Description: "Whether to keep outdated console output in watch mode instead of clearing the screen."
Since the `pretty?` compiler options flag is marked as `@internal`, made this one too.

Author: Josh Goldberg

src/compiler/commandLineParser.ts

@@ -62,6 +62,13 @@ namespace ts {
             category: Diagnostics.Command_line_Options,
             description: Diagnostics.Stylize_errors_and_messages_using_color_and_context_experimental
         },
+        {
+            name: "preserveWatchOutput",
+            type: "boolean",
+            showInSimplifiedHelpView: false,
+            category: Diagnostics.Command_line_Options,
+            description: Diagnostics.Whether_to_keep_outdated_console_output_in_watch_mode_instead_of_clearing_the_screen,
+        },
         {
             name: "watch",
             shortName: "w",

src/compiler/diagnosticMessages.json

@@ -3472,6 +3472,10 @@
         "category": "Message",
         "code": 6190
     },
+    "Whether to keep outdated console output in watch mode instead of clearing the screen.": {
+        "category": "Message",
+        "code": 6191
+    },
     "Variable '{0}' implicitly has an '{1}' type.": {
         "category": "Error",
         "code": 7005

src/compiler/types.ts

@@ -4100,6 +4100,7 @@ namespace ts {
         /*@internal*/ plugins?: PluginImport[];
         preserveConstEnums?: boolean;
         preserveSymlinks?: boolean;
+        /* @internal */ preserveWatchOutput?: boolean;
         project?: string;
         /* @internal */ pretty?: DiagnosticStyle;
         reactNamespace?: string;

src/compiler/watch.ts

@@ -33,6 +33,7 @@ namespace ts {
 
     function clearScreenIfNotWatchingForFileChanges(system: System, diagnostic: Diagnostic, options: CompilerOptions) {
         if (system.clearScreen &&
+            !options.preserveWatchOutput &&
             diagnostic.code !== Diagnostics.Compilation_complete_Watching_for_file_changes.code &&
             !options.extendedDiagnostics &&
             !options.diagnostics) {

src/harness/unittests/tscWatchMode.ts

@@ -2162,7 +2162,7 @@ declare module "fs" {
     });
 
     describe("tsc-watch console clearing", () => {
-        function checkConsoleClearing(diagnostics: boolean, extendedDiagnostics: boolean) {
+        function checkConsoleClearing(options: CompilerOptions = {}) {
             const file = {
                 path: "f.ts",
                 content: ""
@@ -2172,7 +2172,7 @@ declare module "fs" {
             let clearCount: number | undefined;
             checkConsoleClears();
 
-            createWatchOfFilesAndCompilerOptions([file.path], host, { diagnostics, extendedDiagnostics });
+            createWatchOfFilesAndCompilerOptions([file.path], host, options);
             checkConsoleClears();
 
             file.content = "//";
@@ -2182,10 +2182,10 @@ declare module "fs" {
             checkConsoleClears();
 
             function checkConsoleClears() {
-                if (clearCount === undefined) {
+                if (clearCount === undefined || options.preserveWatchOutput) {
                     clearCount = 0;
                 }
-                else if (!diagnostics && !extendedDiagnostics) {
+                else if (!options.diagnostics && !options.extendedDiagnostics) {
                     clearCount++;
                 }
                 host.checkScreenClears(clearCount);
@@ -2194,13 +2194,22 @@ declare module "fs" {
         }
 
         it("without --diagnostics or --extendedDiagnostics", () => {
-            checkConsoleClearing(/*diagnostics*/ false, /*extendedDiagnostics*/ false);
+            checkConsoleClearing();
         });
         it("with --diagnostics", () => {
-            checkConsoleClearing(/*diagnostics*/ true, /*extendedDiagnostics*/ false);
+            checkConsoleClearing({
+                diagnostics: true,
+            });
         });
         it("with --extendedDiagnostics", () => {
-            checkConsoleClearing(/*diagnostics*/ false, /*extendedDiagnostics*/ true);
+            checkConsoleClearing({
+                extendedDiagnostics: true,
+            });
+        });
+        it("with --preserveWatchOutput", () => {
+            checkConsoleClearing({
+                preserveWatchOutput: true,
+            });
         });
     });
 }