@rushstack/rush-sdk 5.101.1 → 5.102.0

package/dist/rush-lib.d.ts

@@ -307,6 +307,58 @@ export declare class CredentialCache {
     private _validate;
 }
 
+/**
+ * An identifier representing a Rush message that can be customized by
+ * defining a custom tip in `common/config/rush/custom-tips.json`.
+ * @remarks
+ * Custom tip ids always start with the `TIP_` prefix.
+ *
+ * @privateRemarks
+ * Events from the Rush process should with "TIP_RUSH_".
+ * Events from a PNPM subprocess should start with "TIP_PNPM_".
+ *
+ * @beta
+ */
+export declare type CustomTipId = 'TIP_RUSH_INCONSISTENT_VERSIONS' | string;
+
+/**
+ * Used to access the `common/config/rush/custom-tips.json` config file,
+ * which allows repo maintainers to configure extra details to be printed alongside
+ * certain Rush messages.
+ * @beta
+ */
+export declare class CustomTipsConfiguration {
+    private static _jsonSchema;
+    private readonly _tipMap;
+    private readonly _jsonFileName;
+    /**
+     * The JSON settings loaded from `custom-tips.json`.
+     */
+    readonly configuration: Readonly<ICustomTipsJson>;
+    /**
+     * The list of identifiers that are allowed to be used in the "tipId" field
+     * of the config file.
+     */
+    static readonly supportedTipIds: ReadonlySet<string>;
+    constructor(configFilename: string);
+    private _formatTipMessage;
+    /**
+     * If custom-tips.json defines a tip for the specified tipId,
+     * display the tip on the terminal.
+     */
+    showInfoTip(terminal: ITerminal, tipId: CustomTipId): void;
+    /**
+     * If custom-tips.json defines a tip for the specified tipId,
+     * display the tip on the terminal.
+     */
+    showWarningTip(terminal: ITerminal, tipId: CustomTipId): void;
+    /**
+     * If custom-tips.json defines a tip for the specified tipId,
+     * display the tip on the terminal.
+     */
+    showErrorTip(terminal: ITerminal, tipId: CustomTipId): void;
+}
+
 /**
  * @public
  */
@@ -812,6 +864,45 @@ export declare interface ICredentialCacheOptions {
     supportEditing: boolean;
 }
 
+/**
+ * An item from the {@link ICustomTipsJson.customTips} list.
+ * @beta
+ */
+export declare interface ICustomTipItemJson {
+    /**
+     * (REQUIRED) An identifier indicating a message that may be printed by Rush.
+     * If that message is printed, then this custom tip will be shown.
+     * Consult the Rush documentation for the current list of possible identifiers.
+     */
+    tipId: CustomTipId;
+    /**
+     * (REQUIRED) The message text to be displayed for this tip.
+     */
+    message: string;
+    /**
+     *  Overrides the "defaultMessagePrefix" for this tip.
+     * Specify an empty string to omit the "defaultMessagePrefix" entirely.
+     */
+    messagePrefix?: string;
+}
+
+/**
+ * This interface represents the raw custom-tips.json file which allows repo maintainers
+ * to configure extra details to be printed alongside certain Rush messages.
+ * @beta
+ */
+export declare interface ICustomTipsJson {
+    /**
+     * If specified, this prefix will be prepended to any the tip messages when they are displayed.
+     * The default value is an empty string.
+     */
+    defaultMessagePrefix?: string;
+    /**
+     *  Specifies the custom tips to be displayed by Rush.
+     */
+    customTips?: ICustomTipItemJson[];
+}
+
 declare interface IEnvironment {
     [environmentVariableName: string]: string | undefined;
 }
@@ -865,6 +956,12 @@ export declare interface IExperimentsJson {
      * Set this option to true to pass '--prefer-frozen-lockfile' instead.
      */
     usePnpmPreferFrozenLockfileForRushUpdate?: boolean;
+    /**
+     * By default, 'rush update' runs as a single operation.
+     * Set this option to true to instead update the lockfile with `--lockfile-only`, then perform a `--frozen-lockfile` install.
+     * Necessary when using the `afterAllResolved` hook in .pnpmfile.cjs.
+     */
+    usePnpmLockfileOnlyThenFrozenLockfileForRushUpdate?: boolean;
     /**
      * If using the 'preventManualShrinkwrapChanges' option, restricts the hash to only include the layout of external dependencies.
      * Used to allow links between workspace projects or the addition/removal of references to existing dependency versions to not
@@ -2907,6 +3004,16 @@ export declare class RushConfiguration {
      * @beta
      */
     readonly versionPolicyConfigurationFilePath: string;
+    /**
+     * Accesses the custom-tips.json configuration.
+     * @beta
+     */
+    readonly customTipsConfiguration: CustomTipsConfiguration;
+    /**
+     * The absolute path to the custom tips configuration file.
+     * @beta
+     */
+    readonly customTipsConfigurationFilePath: string;
     /**
      * This configuration object contains settings repo maintainers have specified to enable
      * and disable experimental Rush features.
@@ -3375,6 +3482,12 @@ export declare class RushConstants {
      * store the state of various features as they stand in the repo.
      */
     static readonly repoStateFilename: string;
+    /**
+     * 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.
+     */
+    static readonly customTipsFilename: string;
     /**
      * 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.

package/lib/api/CustomTipsConfiguration.d.ts

@@ -0,0 +1,89 @@
+import { ITerminal } from '@rushstack/node-core-library';
+/**
+ * This interface represents the raw custom-tips.json file which allows repo maintainers
+ * to configure extra details to be printed alongside certain Rush messages.
+ * @beta
+ */
+export interface ICustomTipsJson {
+    /**
+     * If specified, this prefix will be prepended to any the tip messages when they are displayed.
+     * The default value is an empty string.
+     */
+    defaultMessagePrefix?: string;
+    /**
+     *  Specifies the custom tips to be displayed by Rush.
+     */
+    customTips?: ICustomTipItemJson[];
+}
+/**
+ * An item from the {@link ICustomTipsJson.customTips} list.
+ * @beta
+ */
+export interface ICustomTipItemJson {
+    /**
+     * (REQUIRED) An identifier indicating a message that may be printed by Rush.
+     * If that message is printed, then this custom tip will be shown.
+     * Consult the Rush documentation for the current list of possible identifiers.
+     */
+    tipId: CustomTipId;
+    /**
+     * (REQUIRED) The message text to be displayed for this tip.
+     */
+    message: string;
+    /**
+     *  Overrides the "defaultMessagePrefix" for this tip.
+     * Specify an empty string to omit the "defaultMessagePrefix" entirely.
+     */
+    messagePrefix?: string;
+}
+/**
+ * An identifier representing a Rush message that can be customized by
+ * defining a custom tip in `common/config/rush/custom-tips.json`.
+ * @remarks
+ * Custom tip ids always start with the `TIP_` prefix.
+ *
+ * @privateRemarks
+ * Events from the Rush process should with "TIP_RUSH_".
+ * Events from a PNPM subprocess should start with "TIP_PNPM_".
+ *
+ * @beta
+ */
+export type CustomTipId = 'TIP_RUSH_INCONSISTENT_VERSIONS' | string;
+/**
+ * Used to access the `common/config/rush/custom-tips.json` config file,
+ * which allows repo maintainers to configure extra details to be printed alongside
+ * certain Rush messages.
+ * @beta
+ */
+export declare class CustomTipsConfiguration {
+    private static _jsonSchema;
+    private readonly _tipMap;
+    private readonly _jsonFileName;
+    /**
+     * The JSON settings loaded from `custom-tips.json`.
+     */
+    readonly configuration: Readonly<ICustomTipsJson>;
+    /**
+     * The list of identifiers that are allowed to be used in the "tipId" field
+     * of the config file.
+     */
+    static readonly supportedTipIds: ReadonlySet<string>;
+    constructor(configFilename: string);
+    private _formatTipMessage;
+    /**
+     * If custom-tips.json defines a tip for the specified tipId,
+     * display the tip on the terminal.
+     */
+    showInfoTip(terminal: ITerminal, tipId: CustomTipId): void;
+    /**
+     * If custom-tips.json defines a tip for the specified tipId,
+     * display the tip on the terminal.
+     */
+    showWarningTip(terminal: ITerminal, tipId: CustomTipId): void;
+    /**
+     * If custom-tips.json defines a tip for the specified tipId,
+     * display the tip on the terminal.
+     */
+    showErrorTip(terminal: ITerminal, tipId: CustomTipId): void;
+}
+//# sourceMappingURL=CustomTipsConfiguration.d.ts.map

package/lib/api/CustomTipsConfiguration.js

@@ -0,0 +1 @@
+module.exports = require("../../lib-shim/index")._rushSdk_loadInternalModule("api/CustomTipsConfiguration");

package/lib/api/ExperimentsConfiguration.d.ts

@@ -14,6 +14,12 @@ export interface IExperimentsJson {
      * Set this option to true to pass '--prefer-frozen-lockfile' instead.
      */
     usePnpmPreferFrozenLockfileForRushUpdate?: boolean;
+    /**
+     * By default, 'rush update' runs as a single operation.
+     * Set this option to true to instead update the lockfile with `--lockfile-only`, then perform a `--frozen-lockfile` install.
+     * Necessary when using the `afterAllResolved` hook in .pnpmfile.cjs.
+     */
+    usePnpmLockfileOnlyThenFrozenLockfileForRushUpdate?: boolean;
     /**
      * If using the 'preventManualShrinkwrapChanges' option, restricts the hash to only include the layout of external dependencies.
      * Used to allow links between workspace projects or the addition/removal of references to existing dependency versions to not

package/lib/api/RushConfiguration.d.ts

@@ -13,6 +13,7 @@ import { IPnpmOptionsJson, PnpmOptionsConfiguration } from '../logic/pnpm/PnpmOp
 import { INpmOptionsJson, NpmOptionsConfiguration } from '../logic/npm/NpmOptionsConfiguration';
 import { IYarnOptionsJson, YarnOptionsConfiguration } from '../logic/yarn/YarnOptionsConfiguration';
 import { PackageManagerOptionsConfigurationBase } from '../logic/base/BasePackageManagerOptionsConfiguration';
+import { CustomTipsConfiguration } from './CustomTipsConfiguration';
 /**
  * Part of IRushConfigurationJson.
  */
@@ -413,6 +414,16 @@ export declare class RushConfiguration {
      * @beta
      */
     readonly versionPolicyConfigurationFilePath: string;
+    /**
+     * Accesses the custom-tips.json configuration.
+     * @beta
+     */
+    readonly customTipsConfiguration: CustomTipsConfiguration;
+    /**
+     * The absolute path to the custom tips configuration file.
+     * @beta
+     */
+    readonly customTipsConfigurationFilePath: string;
     /**
      * This configuration object contains settings repo maintainers have specified to enable
      * and disable experimental Rush features.

package/lib/cli/actions/BaseInstallAction.d.ts

@@ -2,10 +2,12 @@ import type { CommandLineFlagParameter, CommandLineIntegerParameter, CommandLine
 import { BaseRushAction, IBaseRushActionOptions } from './BaseRushAction';
 import type { IInstallManagerOptions } from '../../logic/base/BaseInstallManagerTypes';
 import { SelectionParameterSet } from '../parsing/SelectionParameterSet';
+import { ITerminal } from '@rushstack/node-core-library';
 /**
  * This is the common base class for InstallAction and UpdateAction.
  */
 export declare abstract class BaseInstallAction extends BaseRushAction {
+    protected readonly _terminal: ITerminal;
     protected readonly _variant: CommandLineStringParameter;
     protected readonly _purgeParameter: CommandLineFlagParameter;
     protected readonly _bypassPolicyParameter: CommandLineFlagParameter;

package/lib/cli/actions/CheckAction.d.ts

@@ -1,6 +1,7 @@
 import { RushCommandLineParser } from '../RushCommandLineParser';
 import { BaseRushAction } from './BaseRushAction';
 export declare class CheckAction extends BaseRushAction {
+    private readonly _terminal;
     private readonly _variant;
     private readonly _jsonFlag;
     private readonly _verboseFlag;

package/lib/index.d.ts

@@ -31,6 +31,7 @@ export { VersionPolicyConfiguration } from './api/VersionPolicyConfiguration';
 export { ILaunchOptions, Rush } from './api/Rush';
 export { RushInternals as _RushInternals } from './api/RushInternals';
 export { ExperimentsConfiguration, IExperimentsJson } from './api/ExperimentsConfiguration';
+export { CustomTipsConfiguration, CustomTipId, ICustomTipsJson, ICustomTipItemJson } from './api/CustomTipsConfiguration';
 export { ProjectChangeAnalyzer, IGetChangedProjectsOptions } from './logic/ProjectChangeAnalyzer';
 export { IOperationRunner, IOperationRunnerContext } from './logic/operations/IOperationRunner';
 export { IExecutionResult, IOperationExecutionResult } from './logic/operations/IOperationExecutionResult';

package/lib/logic/RushConstants.d.ts

@@ -108,6 +108,12 @@ export declare class RushConstants {
      * store the state of various features as they stand in the repo.
      */
     static readonly repoStateFilename: string;
+    /**
+     * 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.
+     */
+    static readonly customTipsFilename: string;
     /**
      * 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.

package/lib/logic/base/BaseInstallManagerTypes.d.ts

@@ -29,6 +29,10 @@ export interface IInstallManagerOptions {
      * will be upgraded to the latest SemVer-compatible version.
      */
     fullUpgrade: boolean;
+    /**
+     * If set, only update the shrinkwrap file; do not create node_modules.
+     */
+    onlyShrinkwrap?: boolean;
     /**
      * Whether to force an update to the shrinkwrap file even if it appears to be unnecessary.
      * Normally Rush uses heuristics to determine when "pnpm install" can be skipped,

package/lib/logic/versionMismatch/VersionMismatchFinder.d.ts

@@ -1,3 +1,4 @@
+import { ITerminal } from '@rushstack/node-core-library';
 import { RushConfiguration } from '../../api/RushConfiguration';
 import { VersionMismatchFinderEntity } from './VersionMismatchFinderEntity';
 export interface IVersionMismatchFinderOptions {
@@ -27,8 +28,8 @@ export declare class VersionMismatchFinder {
     private _mismatches;
     private _projects;
     constructor(projects: VersionMismatchFinderEntity[], allowedAlternativeVersions?: Map<string, ReadonlyArray<string>>);
-    static rushCheck(rushConfiguration: RushConfiguration, options?: IVersionMismatchFinderRushCheckOptions): void;
-    static ensureConsistentVersions(rushConfiguration: RushConfiguration, options?: IVersionMismatchFinderEnsureConsistentVersionsOptions): void;
+    static rushCheck(rushConfiguration: RushConfiguration, terminal: ITerminal, options?: IVersionMismatchFinderRushCheckOptions): void;
+    static ensureConsistentVersions(rushConfiguration: RushConfiguration, terminal: ITerminal, options?: IVersionMismatchFinderEnsureConsistentVersionsOptions): void;
     /**
      * Populates a version mismatch finder object given a Rush Configuration.
      * Intentionally considers preferred versions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/rush-sdk",
-  "version": "5.101.1",
+  "version": "5.102.0",
   "description": "An API for interacting with the Rush engine",
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
     "@types/node": "14.18.36",
     "@types/semver": "7.5.0",
     "@types/webpack-env": "1.18.0",
-    "@microsoft/rush-lib": "5.101.1",
+    "@microsoft/rush-lib": "5.102.0",
     "@rushstack/eslint-config": "3.3.3",
     "@rushstack/heft": "0.58.2",
     "@rushstack/heft-node-rig": "2.2.22",