feat(rush-lib): setup Rush Custom Tips

build-tests/install-test-workspace/workspace/rush-lib-test/src/start.ts

@@ -14,5 +14,7 @@ console.log('Calling an internal API...');
 
 // Use a path-based import to access an internal API (do so at your own risk!)
 import { VersionMismatchFinder } from '@microsoft/rush-lib/lib/logic/versionMismatch/VersionMismatchFinder';
+import { ConsoleTerminalProvider, Terminal } from '@rushstack/node-core-library';
 
-VersionMismatchFinder.ensureConsistentVersions(config);
+const terminal = new Terminal(new ConsoleTerminalProvider());
+VersionMismatchFinder.ensureConsistentVersions(config, terminal);

common/changes/@microsoft/rush/feat-rush-custom-tips_2023-06-15-18-23.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add a new config file \"custom-tips.json\" for customizing Rush messages (GitHub #4207)",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/reviews/api/rush-lib.api.md

@@ -125,6 +125,30 @@ export class CredentialCache {
     static usingAsync(options: ICredentialCacheOptions, doActionAsync: (credentialCache: CredentialCache) => Promise<void> | void): Promise<void>;
 }
 
+// @beta (undocumented)
+export type CustomTipId = 'PNPM_MISMATCH_DEPENDENCY' | string;
+
+// @beta (undocumented)
+export class CustomTipsConfiguration {
+    constructor(configFilename: string);
+    // (undocumented)
+    readonly configuration: Readonly<ICustomTipsJson>;
+    // (undocumented)
+    static readonly knownTipIds: ReadonlySet<string>;
+    // (undocumented)
+    log(tipId: CustomTipId, terminal: ITerminal): void;
+}
+
+// @beta (undocumented)
+export enum CustomTipSeverity {
+    // (undocumented)
+    error = 2,
+    // (undocumented)
+    log = 0,
+    // (undocumented)
+    warning = 1
+}
+
 // @public (undocumented)
 export enum DependencyType {
     // (undocumented)
@@ -285,6 +309,26 @@ export interface ICredentialCacheOptions {
     supportEditing: boolean;
 }
 
+// @beta (undocumented)
+export interface ICustomTipItemJson {
+    // (undocumented)
+    id: CustomTipId;
+    // (undocumented)
+    prefix?: string;
+    // (undocumented)
+    severity?: CustomTipSeverity;
+    // (undocumented)
+    tip: string;
+}
+
+// @beta (undocumented)
+export interface ICustomTipsJson {
+    // (undocumented)
+    customTips?: ICustomTipItemJson[];
+    // (undocumented)
+    prefix?: string;
+}
+
 // @beta (undocumented)
 export interface IEnvironmentConfigurationInitializeOptions {
     // (undocumented)
@@ -844,6 +888,10 @@ export class RushConfiguration {
     get commonVersions(): CommonVersionsConfiguration;
     get currentInstalledVariant(): string | undefined;
     readonly currentVariantJsonFilename: string;
+    // @beta (undocumented)
+    readonly customTipsConfiguration: CustomTipsConfiguration;
+    // (undocumented)
+    readonly customTipsConfigurationFilePath: string;
     readonly ensureConsistentVersions: boolean;
     // @beta
     readonly eventHooks: EventHooks;
@@ -977,6 +1025,7 @@ export class RushConstants {
     static readonly commandLineFilename: string;
     static readonly commonFolderName: string;
     static readonly commonVersionsFilename: string;
+    static readonly customTipsFilename: string;
     static readonly defaultMaxInstallAttempts: number;
     static readonly defaultWatchDebounceMs: number;
     static readonly experimentsFilename: string;

libraries/rush-lib/src/api/CustomTipsConfiguration.ts

@@ -0,0 +1,105 @@
+import * as path from 'path';
+import { FileSystem, ITerminal, JsonFile, JsonSchema } from '@rushstack/node-core-library';
+
+import schemaJson from '../schemas/custom-tips.schema.json';
+
+/**
+ * @beta
+ */
+export interface ICustomTipsJson {
+  prefix?: string;
+  customTips?: ICustomTipItemJson[];
+}
+/**
+ * @beta
+ */
+export interface ICustomTipItemJson {
+  id: CustomTipId;
+  tip: string;
+  prefix?: string;
+  severity?: CustomTipSeverity;
+}
+
+/**
+ * @beta
+ */
+export enum CustomTipSeverity {
+  log = 0,
+  warning = 1,
+  error = 2
+}
+
+/**
+ * @beta
+ */
+export type CustomTipId = 'PNPM_MISMATCH_DEPENDENCY' | string;
+
+/**
+ * @beta
+ */
+export class CustomTipsConfiguration {
+  private static _jsonSchema: JsonSchema = JsonSchema.fromLoadedObject(schemaJson);
+
+  private readonly _tipMap: Map<CustomTipId, ICustomTipItemJson>;
+  private readonly _jsonFileName: string;
+
+  public readonly configuration: Readonly<ICustomTipsJson>;
+
+  public static readonly knownTipIds: ReadonlySet<string> = new Set<string>(['PNPM_MISMATCH_DEPENDENCY']);
+
+  public constructor(configFilename: string) {
+    this._jsonFileName = configFilename;
+    this._tipMap = new Map();
+
+    if (!FileSystem.exists(this._jsonFileName)) {
+      this.configuration = {};
+    } else {
+      this.configuration = JsonFile.loadAndValidate(this._jsonFileName, CustomTipsConfiguration._jsonSchema);
+
+      const customTips: ICustomTipItemJson[] | undefined = this.configuration?.customTips;
+      if (customTips) {
+        for (const tipItem of customTips) {
+          if (!CustomTipsConfiguration.knownTipIds.has(tipItem.id)) {
+            throw new Error(
+              `The ${path.basename(this._jsonFileName)} configuration` +
+                ` references an unknown ID "${tipItem.id}"`
+            );
+          }
+          if (this._tipMap.has(tipItem.id)) {
+            throw new Error(
+              `The ${path.basename(this._jsonFileName)} configuration` +
+                ` specifies a duplicate definition for "${tipItem.id}"`
+            );
+          }
+          this._tipMap.set(tipItem.id, tipItem);
+        }
+      }
+    }
+  }
+
+  /**
+   *
+   * @param tipId - All the `tipId` options are in this doc: TODO: add link to doc
+   */
+  public log(tipId: CustomTipId, terminal: ITerminal): void {
+    const customTipItem: ICustomTipItemJson | undefined = this._tipMap.get(tipId);
+
+    if (!customTipItem) {
+      return;
+    }
+
+    const prefix: string | undefined = customTipItem.prefix ?? this.configuration.prefix;
+    const tipString: string = `${prefix ?? ''}${customTipItem.tip}`;
+    switch (customTipItem.severity) {
+      case CustomTipSeverity.log:
+        terminal.writeLine(tipString);
+        break;
+      case CustomTipSeverity.warning:
+        terminal.writeWarningLine(tipString);
+        break;
+      default:
+        terminal.writeErrorLine(tipString);
+        break;
+    }
+  }
+}

libraries/rush-lib/src/api/RushConfiguration.ts

@@ -41,6 +41,7 @@ import schemaJson from '../schemas/rush.schema.json';
 
 import type * as DependencyAnalyzerModuleType from '../logic/DependencyAnalyzer';
 import { PackageManagerOptionsConfigurationBase } from '../logic/base/BasePackageManagerOptionsConfiguration';
+import { CustomTipsConfiguration } from './CustomTipsConfiguration';
 
 const MINIMUM_SUPPORTED_RUSH_JSON_VERSION: string = '0.0.0';
 const DEFAULT_BRANCH: string = 'main';
@@ -59,6 +60,7 @@ const knownRushConfigFilenames: string[] = [
   RushConstants.buildCacheFilename,
   RushConstants.commandLineFilename,
   RushConstants.commonVersionsFilename,
+  RushConstants.customTipsFilename,
   RushConstants.experimentsFilename,
   RushConstants.nonbrowserApprovedPackagesFilename,
   RushConstants.pinnedVersionsFilename,
@@ -535,6 +537,16 @@ export class RushConfiguration {
    */
   public readonly versionPolicyConfigurationFilePath: string;
 
+  /**
+   * @beta
+   */
+  public readonly customTipsConfiguration: CustomTipsConfiguration;
+
+  /**
+   *
+   */
+  public readonly customTipsConfigurationFilePath: string;
+
   /**
    * This configuration object contains settings repo maintainers have specified to enable
    * and disable experimental Rush features.
@@ -805,6 +817,12 @@ export class RushConfiguration {
     );
     this.versionPolicyConfiguration = new VersionPolicyConfiguration(this.versionPolicyConfigurationFilePath);
 
+    this.customTipsConfigurationFilePath = path.join(
+      this.commonRushConfigFolder,
+      RushConstants.customTipsFilename
+    );
+    this.customTipsConfiguration = new CustomTipsConfiguration(this.customTipsConfigurationFilePath);
+
     this._variants = new Set<string>();
 
     if (rushConfigurationJson.variants) {

libraries/rush-lib/src/api/test/CustomTipsConfiguration.test.ts

@@ -0,0 +1,16 @@
+import { CustomTipsConfiguration } from '../CustomTipsConfiguration';
+import { RushConfiguration } from '../RushConfiguration';
+
+describe(CustomTipsConfiguration.name, () => {
+  it('loads the config file (custom-tips.json)', () => {
+    const rushFilename: string = `${__dirname}/repo/rush-npm.json`;
+    const rushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(rushFilename);
+    expect(rushConfiguration.customTipsConfiguration.configuration.customTips?.length).toBe(1);
+  });
+
+  it('reports an error for duplicate tips', () => {
+    expect(() => {
+      new CustomTipsConfiguration(`${__dirname}/jsonFiles/custom-tips.error.json`);
+    }).toThrowError('PNPM_MISMATCH_DEPENDENCY');
+  });
+});

libraries/rush-lib/src/api/test/jsonFiles/custom-tips.error.json

@@ -0,0 +1,12 @@
+{
+  "customTips": [
+    {
+      "id": "PNPM_MISMATCH_DEPENDENCY",
+      "tip": "definition 1"
+    },
+    {
+      "id": "PNPM_MISMATCH_DEPENDENCY",
+      "tip": "definition 2"
+    }
+  ]
+}

libraries/rush-lib/src/api/test/repo/common/config/rush/custom-tips.json

@@ -0,0 +1,14 @@
+{
+  // "$schema": todo need a link
+  // The prefix will be prepended to all the custom message.
+  "prefix": "⭐️ [Monorepo Infra team tip]: ",
+
+  "customTips": [
+    {
+      "id": "PNPM_MISMATCH_DEPENDENCY",
+      "tip": "This is so wrong my friend. Please read this doc for more information: google.com"
+      // "prefix": "" // override the global prefix.
+      // "severity": "error" // default to error for more visibility
+    }
+  ]
+}

libraries/rush-lib/src/cli/actions/BaseInstallAction.ts

@@ -21,11 +21,13 @@ import { VersionMismatchFinder } from '../../logic/versionMismatch/VersionMismat
 import { Variants } from '../../api/Variants';
 import { RushConstants } from '../../logic/RushConstants';
 import { SelectionParameterSet } from '../parsing/SelectionParameterSet';
+import { ConsoleTerminalProvider, ITerminal, Terminal } from '@rushstack/node-core-library';
 
 /**
  * This is the common base class for InstallAction and UpdateAction.
  */
 export abstract class BaseInstallAction extends BaseRushAction {
+  protected readonly _terminal: ITerminal;
   protected readonly _variant: CommandLineStringParameter;
   protected readonly _purgeParameter: CommandLineFlagParameter;
   protected readonly _bypassPolicyParameter: CommandLineFlagParameter;
@@ -43,6 +45,8 @@ export abstract class BaseInstallAction extends BaseRushAction {
   public constructor(options: IBaseRushActionOptions) {
     super(options);
 
+    this._terminal = new Terminal(new ConsoleTerminalProvider({ verboseEnabled: options.parser.isDebug }));
+
     this._purgeParameter = this.defineFlagParameter({
       parameterLongName: '--purge',
       parameterShortName: '-p',
@@ -90,7 +94,7 @@ export abstract class BaseInstallAction extends BaseRushAction {
   protected abstract buildInstallOptionsAsync(): Promise<IInstallManagerOptions>;
 
   protected async runAsync(): Promise<void> {
-    VersionMismatchFinder.ensureConsistentVersions(this.rushConfiguration, {
+    VersionMismatchFinder.ensureConsistentVersions(this.rushConfiguration, this._terminal, {
       variant: this._variant.value
     });
 

libraries/rush-lib/src/cli/actions/CheckAction.ts

@@ -8,8 +8,10 @@ import { RushCommandLineParser } from '../RushCommandLineParser';
 import { BaseRushAction } from './BaseRushAction';
 import { VersionMismatchFinder } from '../../logic/versionMismatch/VersionMismatchFinder';
 import { Variants } from '../../api/Variants';
+import { ConsoleTerminalProvider, ITerminal, Terminal } from '@rushstack/node-core-library';
 
 export class CheckAction extends BaseRushAction {
+  private readonly _terminal: ITerminal;
   private readonly _variant: CommandLineStringParameter;
   private readonly _jsonFlag: CommandLineFlagParameter;
   private readonly _verboseFlag: CommandLineFlagParameter;
@@ -27,6 +29,7 @@ export class CheckAction extends BaseRushAction {
       parser
     });
 
+    this._terminal = new Terminal(new ConsoleTerminalProvider({ verboseEnabled: parser.isDebug }));
     this._variant = this.defineStringParameter(Variants.VARIANT_PARAMETER);
     this._jsonFlag = this.defineFlagParameter({
       parameterLongName: '--json',
@@ -52,7 +55,7 @@ export class CheckAction extends BaseRushAction {
       );
     }
 
-    VersionMismatchFinder.rushCheck(this.rushConfiguration, {
+    VersionMismatchFinder.rushCheck(this.rushConfiguration, this._terminal, {
       variant: this._variant.value,
       printAsJson: this._jsonFlag.value,
       truncateLongPackageNameLists: !this._verboseFlag.value

libraries/rush-lib/src/cli/scriptActions/PhasedScriptAction.ts

@@ -242,6 +242,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> {
       );
 
       await doBasicInstallAsync({
+        terminal: this._terminal,
         rushConfiguration: this.rushConfiguration,
         rushGlobalFolder: this.rushGlobalFolder,
         isDebug: this.parser.isDebug

libraries/rush-lib/src/index.ts

@@ -90,6 +90,13 @@ export { ILaunchOptions, Rush } from './api/Rush';
 export { RushInternals as _RushInternals } from './api/RushInternals';
 
 export { ExperimentsConfiguration, IExperimentsJson } from './api/ExperimentsConfiguration';
+export {
+  CustomTipsConfiguration,
+  CustomTipId,
+  CustomTipSeverity,
+  ICustomTipsJson,
+  ICustomTipItemJson
+} from './api/CustomTipsConfiguration';
 
 export { ProjectChangeAnalyzer, IGetChangedProjectsOptions } from './logic/ProjectChangeAnalyzer';
 

libraries/rush-lib/src/logic/RushConstants.ts

@@ -132,6 +132,13 @@ export class RushConstants {
    */
   public static readonly repoStateFilename: string = 'repo-state.json';
 
+  /**
+   * The filename ("custom-tips.json") for the file used by Rush to
+   * print user-customized messages.
+   * This configuration file should go in the "common/config/rush" folder.
+   */
+  public static readonly customTipsFilename: string = 'custom-tips.json';
+
   /**
    * The name of the per-project folder where project-specific Rush files are stored. For example,
    * the package-deps files, which are used by commands to determine if a particular project needs to be rebuilt.