Merge pull request #2839 from elliot-nelson/experimental-terminal

[rush] Move ConfigurationFile logging to new "debug" severity

Author: iclanton

apps/rush-lib/src/cli/scriptActions/BulkScriptAction.ts

@@ -110,6 +110,7 @@ export class BulkScriptAction extends BaseScriptAction {
     const stopwatch: Stopwatch = Stopwatch.start();
 
     const isQuietMode: boolean = !this._verboseParameter.value;
+    const isDebugMode: boolean = !!this.parser.isDebug;
 
     // if this is parallelizable, then use the value from the flag (undefined or a number),
     // if parallelism is not enabled, then restrict to 1 core
@@ -144,6 +145,7 @@ export class BulkScriptAction extends BaseScriptAction {
       commandToRun: this._commandToRun,
       customParameterValues,
       isQuietMode: isQuietMode,
+      isDebugMode: isDebugMode,
       isIncrementalBuildAllowed: this._isIncrementalBuildAllowed,
       ignoreMissingScript: this._ignoreMissingScript,
       ignoreDependencyOrder: this._ignoreDependencyOrder,
@@ -152,6 +154,7 @@ export class BulkScriptAction extends BaseScriptAction {
 
     const taskRunnerOptions: ITaskRunnerOptions = {
       quietMode: isQuietMode,
+      debugMode: this.parser.isDebug,
       parallelism: parallelism,
       changedProjectsOnly: changedProjectsOnly,
       allowWarningsInSuccessfulBuild: this._allowWarningsInSuccessfulBuild,

apps/rush-lib/src/logic/TaskSelector.ts

@@ -16,6 +16,7 @@ export interface ITaskSelectorConstructor {
   commandToRun: string;
   customParameterValues: string[];
   isQuietMode: boolean;
+  isDebugMode: boolean;
   isIncrementalBuildAllowed: boolean;
   ignoreMissingScript: boolean;
   ignoreDependencyOrder: boolean;

apps/rush-lib/src/logic/taskRunner/BaseBuilder.ts

@@ -12,6 +12,7 @@ export interface IBuilderContext {
   collatedWriter: CollatedWriter;
   stdioSummarizer: StdioSummarizer;
   quietMode: boolean;
+  debugMode: boolean;
 }
 
 /**

apps/rush-lib/src/logic/taskRunner/ProjectBuilder.ts

@@ -167,12 +167,12 @@ export class ProjectBuilder extends BaseBuilder {
         newlineKind: NewlineKind.Lf // for StdioSummarizer
       });
 
-      const quietModeTransform: DiscardStdoutTransform = new DiscardStdoutTransform({
+      const discardTransform: DiscardStdoutTransform = new DiscardStdoutTransform({
         destination: context.collatedWriter
       });
 
       const splitterTransform1: SplitterTransform = new SplitterTransform({
-        destinations: [context.quietMode ? quietModeTransform : context.collatedWriter, stderrLineTransform]
+        destinations: [context.quietMode ? discardTransform : context.collatedWriter, stderrLineTransform]
       });
 
       const normalizeNewlineTransform: TextRewriterTransform = new TextRewriterTransform({
@@ -182,7 +182,9 @@ export class ProjectBuilder extends BaseBuilder {
       });
 
       const collatedTerminal: CollatedTerminal = new CollatedTerminal(normalizeNewlineTransform);
-      const terminalProvider: CollatedTerminalProvider = new CollatedTerminalProvider(collatedTerminal);
+      const terminalProvider: CollatedTerminalProvider = new CollatedTerminalProvider(collatedTerminal, {
+        debugEnabled: context.debugMode
+      });
       const terminal: Terminal = new Terminal(terminalProvider);
 
       let hasWarningOrError: boolean = false;

apps/rush-lib/src/logic/taskRunner/TaskRunner.ts

@@ -21,6 +21,7 @@ import { CommandLineConfiguration } from '../../api/CommandLineConfiguration';
 
 export interface ITaskRunnerOptions {
   quietMode: boolean;
+  debugMode: boolean;
   parallelism: string | undefined;
   changedProjectsOnly: boolean;
   allowWarningsInSuccessfulBuild: boolean;
@@ -43,6 +44,7 @@ export class TaskRunner {
   private readonly _allowWarningsInSuccessfulBuild: boolean;
   private readonly _buildQueue: Task[];
   private readonly _quietMode: boolean;
+  private readonly _debugMode: boolean;
   private readonly _parallelism: number;
   private readonly _repoCommandLineConfiguration: CommandLineConfiguration | undefined;
   private _hasAnyFailures: boolean;
@@ -60,6 +62,7 @@ export class TaskRunner {
   public constructor(orderedTasks: Task[], options: ITaskRunnerOptions) {
     const {
       quietMode,
+      debugMode,
       parallelism,
       changedProjectsOnly,
       allowWarningsInSuccessfulBuild,
@@ -68,6 +71,7 @@ export class TaskRunner {
     this._tasks = orderedTasks;
     this._buildQueue = orderedTasks.slice(0);
     this._quietMode = quietMode;
+    this._debugMode = debugMode;
     this._hasAnyFailures = false;
     this._hasAnyWarnings = false;
     this._changedProjectsOnly = changedProjectsOnly;
@@ -239,7 +243,8 @@ export class TaskRunner {
       repoCommandLineConfiguration: this._repoCommandLineConfiguration,
       stdioSummarizer: task.stdioSummarizer,
       collatedWriter: task.collatedWriter,
-      quietMode: this._quietMode
+      quietMode: this._quietMode,
+      debugMode: this._debugMode
     };
 
     try {

apps/rush-lib/src/logic/taskRunner/test/TaskRunner.test.ts

@@ -63,6 +63,7 @@ describe('TaskRunner', () => {
         () =>
           new TaskRunner([], {
             quietMode: false,
+            debugMode: false,
             parallelism: 'tequila',
             changedProjectsOnly: false,
             destination: mockWritable,
@@ -77,6 +78,7 @@ describe('TaskRunner', () => {
     beforeEach(() => {
       taskRunnerOptions = {
         quietMode: false,
+        debugMode: false,
         parallelism: '1',
         changedProjectsOnly: false,
         destination: mockWritable,
@@ -134,6 +136,7 @@ describe('TaskRunner', () => {
       beforeEach(() => {
         taskRunnerOptions = {
           quietMode: false,
+          debugMode: false,
           parallelism: '1',
           changedProjectsOnly: false,
           destination: mockWritable,
@@ -169,6 +172,7 @@ describe('TaskRunner', () => {
       beforeEach(() => {
         taskRunnerOptions = {
           quietMode: false,
+          debugMode: false,
           parallelism: '1',
           changedProjectsOnly: false,
           destination: mockWritable,

apps/rush-lib/src/utilities/CollatedTerminalProvider.ts

@@ -4,10 +4,15 @@
 import { ITerminalProvider, TerminalProviderSeverity } from '@rushstack/node-core-library';
 import { CollatedTerminal } from '@rushstack/stream-collator';
 
+export interface ICollatedTerminalProviderOptions {
+  debugEnabled: boolean;
+}
+
 export class CollatedTerminalProvider implements ITerminalProvider {
   private readonly _collatedTerminal: CollatedTerminal;
   private _hasErrors: boolean = false;
   private _hasWarnings: boolean = false;
+  private _debugEnabled: boolean = false;
 
   public readonly supportsColor: boolean = true;
   public readonly eolCharacter: string = '\n';
@@ -20,18 +25,34 @@ export class CollatedTerminalProvider implements ITerminalProvider {
     return this._hasWarnings;
   }
 
-  public constructor(collatedTerminal: CollatedTerminal) {
+  public constructor(
+    collatedTerminal: CollatedTerminal,
+    options?: Partial<ICollatedTerminalProviderOptions>
+  ) {
     this._collatedTerminal = collatedTerminal;
+    this._debugEnabled = !!options?.debugEnabled;
   }
 
   public write(data: string, severity: TerminalProviderSeverity): void {
     switch (severity) {
       case TerminalProviderSeverity.log:
       case TerminalProviderSeverity.verbose: {
+        // Unlike the basic ConsoleTerminalProvider, verbose messages are always passed
+        // to stdout -- by convention the user-controlled build script output is sent
+        // to verbose, and will be routed to a variety of other providers in the ProjectBuilder.
         this._collatedTerminal.writeStdoutLine(data);
         break;
       }
 
+      case TerminalProviderSeverity.debug: {
+        // Similar to the basic ConsoleTerminalProvider, debug messages are discarded
+        // unless they are explicitly enabled.
+        if (this._debugEnabled) {
+          this._collatedTerminal.writeStdoutLine(data);
+        }
+        break;
+      }
+
       case TerminalProviderSeverity.error: {
         this._collatedTerminal.writeStderrLine(data);
         this._hasErrors = true;

common/changes/@microsoft/rush/experimental-terminal_2021-08-03-19-33.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "The --debug flag now also shows additional diagnostic information.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "[email protected]"
+}

common/changes/@rushstack/heft-config-file/experimental-terminal_2021-08-03-19-33.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-config-file",
+      "comment": "Move detailed logging from verbose to debug severity.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/heft-config-file",
+  "email": "[email protected]"
+}

common/changes/@rushstack/node-core-library/experimental-terminal_2021-08-03-19-33.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/node-core-library",
+      "comment": "Add new Terminal message severity \"debug\", below verbose.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/node-core-library",
+  "email": "[email protected]"
+}

common/reviews/api/node-core-library.api.md

@@ -120,6 +120,7 @@ export enum ColorValue {
 // @beta
 export class ConsoleTerminalProvider implements ITerminalProvider {
     constructor(options?: Partial<IConsoleTerminalProviderOptions>);
+    debugEnabled: boolean;
     get eolCharacter(): string;
     get supportsColor(): boolean;
     verboseEnabled: boolean;
@@ -289,6 +290,7 @@ export interface IColorableSequence {
 
 // @beta
 export interface IConsoleTerminalProviderOptions {
+    debugEnabled: boolean;
     verboseEnabled: boolean;
 }
 
@@ -718,6 +720,7 @@ export class Sort {
 export class StringBufferTerminalProvider implements ITerminalProvider {
     constructor(supportsColor?: boolean);
     get eolCharacter(): string;
+    getDebugOutput(options?: IStringBufferOutputOptions): string;
     getErrorOutput(options?: IStringBufferOutputOptions): string;
     getOutput(options?: IStringBufferOutputOptions): string;
     getVerbose(options?: IStringBufferOutputOptions): string;
@@ -739,6 +742,8 @@ export class Terminal {
     registerProvider(provider: ITerminalProvider): void;
     unregisterProvider(provider: ITerminalProvider): void;
     write(...messageParts: (string | IColorableSequence)[]): void;
+    writeDebug(...messageParts: (string | IColorableSequence)[]): void;
+    writeDebugLine(...messageParts: (string | IColorableSequence)[]): void;
     writeError(...messageParts: (string | IColorableSequence)[]): void;
     writeErrorLine(...messageParts: (string | IColorableSequence)[]): void;
     writeLine(...messageParts: (string | IColorableSequence)[]): void;
@@ -748,8 +753,10 @@ export class Terminal {
     writeWarningLine(...messageParts: (string | IColorableSequence)[]): void;
 }
 
-// @beta (undocumented)
+// @beta
 export enum TerminalProviderSeverity {
+    // (undocumented)
+    debug = 4,
     // (undocumented)
     error = 2,
     // (undocumented)

libraries/heft-config-file/src/ConfigurationFile.ts

@@ -341,7 +341,7 @@ export class ConfigurationFile<TConfigurationFile> {
     } catch (e) {
       if (FileSystem.isNotExistError(e)) {
         if (rigConfig) {
-          terminal.writeVerboseLine(
+          terminal.writeDebugLine(
             `Config file "${resolvedConfigurationFilePathForLogging}" does not exist. Attempting to load via rig.`
           );
           const rigResult: TConfigurationFile | undefined = await this._tryLoadConfigurationFileInRigAsync(
@@ -353,7 +353,7 @@ export class ConfigurationFile<TConfigurationFile> {
             return rigResult;
           }
         } else {
-          terminal.writeVerboseLine(
+          terminal.writeDebugLine(
             `Configuration file "${resolvedConfigurationFilePathForLogging}" not found.`
           );
         }
@@ -570,15 +570,15 @@ export class ConfigurationFile<TConfigurationFile> {
         if (!FileSystem.isNotExistError(e)) {
           throw e;
         } else {
-          terminal.writeVerboseLine(
+          terminal.writeDebugLine(
             `Configuration file "${
               this.projectRelativeFilePath
             }" not found in rig ("${ConfigurationFile._formatPathForLogging(rigProfileFolder)}")`
           );
         }
       }
     } else {
-      terminal.writeVerboseLine(
+      terminal.writeDebugLine(
         `No rig found for "${ConfigurationFile._formatPathForLogging(rigConfig.projectFolderPath)}"`
       );
     }

libraries/heft-config-file/src/test/ConfigurationFile.test.ts

@@ -34,7 +34,8 @@ describe('ConfigurationFile', () => {
       log: terminalProvider.getOutput(),
       warning: terminalProvider.getWarningOutput(),
       error: terminalProvider.getErrorOutput(),
-      verbose: terminalProvider.getVerbose()
+      verbose: terminalProvider.getVerbose(),
+      debug: terminalProvider.getDebugOutput()
     }).toMatchSnapshot();
   });