MinimalRushConfiguration.ts

// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

import * as path from 'node:path';

import { FileSystem, JsonFile, PackageJsonLookup } from '@rushstack/node-core-library';
import { RushConfiguration } from '@microsoft/rush-lib';
import { EnvironmentConfiguration } from '@microsoft/rush-lib/lib/api/EnvironmentConfiguration';
import { RushConstants } from '@microsoft/rush-lib/lib/logic/RushConstants';
import { RushCommandLineParser } from '@microsoft/rush-lib/lib/cli/RushCommandLineParser';
import { isSupportedReporterName, type ReporterName } from '@rushstack/rush-reporter';

import { getRushPreviewVersion } from './RushPreviewVersion';

interface IMinimalRushConfigurationJson {
  rushMinimumVersion: string;
  rushVersion?: string;
}

interface IMinimalExperimentsConfigurationJson {
  useRushReporter?: boolean;
}

/**
 * Represents a minimal subset of the rush.json configuration file. It provides the information necessary to
 * decide which version of Rush should be installed/used.
 */
export class MinimalRushConfiguration {
  #rushVersion: string;
  #commonRushConfigFolder: string;
  #useRushReporter: boolean;

  private constructor(minimalRushConfigurationJson: IMinimalRushConfigurationJson, rushJsonFilename: string) {
    this.#rushVersion =
      minimalRushConfigurationJson.rushVersion || minimalRushConfigurationJson.rushMinimumVersion;
    this.#commonRushConfigFolder = path.join(
      path.dirname(rushJsonFilename),
      RushConstants.commonFolderName,
      'config',
      'rush'
    );

    const experimentsJsonFilename: string = path.join(
      this.#commonRushConfigFolder,
      RushConstants.experimentsFilename
    );
    const experimentsConfiguration: IMinimalExperimentsConfigurationJson | undefined =
      _loadExperimentsConfigurationJson(experimentsJsonFilename);
    if (
      experimentsConfiguration?.useRushReporter !== undefined &&
      typeof experimentsConfiguration.useRushReporter !== 'boolean'
    ) {
      throw new Error(`The "useRushReporter" setting in "${experimentsJsonFilename}" must be true or false.`);
    }
    this.#useRushReporter = experimentsConfiguration?.useRushReporter === true;
  }

  public static loadFromDefaultLocation(
    writeLine: (message: string) => void = (message) => console.log(message)
  ): MinimalRushConfiguration | undefined {
    const showVerbose: boolean = !RushCommandLineParser.shouldRestrictConsoleOutput();
    const rushJsonLocation: string | undefined = RushConfiguration.tryFindRushJsonLocation({
      showVerbose: false
    });
    if (rushJsonLocation) {
      const minimalRushConfigurationJson: IMinimalRushConfigurationJson | undefined =
        _loadConfigurationJson(rushJsonLocation);
      const explicitReporter: ReporterName | undefined = _getExplicitReporter(process.argv.slice(2));
      const legacyFallbackRequested: boolean =
        explicitReporter === 'legacy' ||
        process.env.RUSH_REPORTER?.trim().toLowerCase() === 'legacy' ||
        _hasHelpControl(process.argv.slice(2));
      let configuration: MinimalRushConfiguration | undefined;
      let legacyPresentation: boolean = legacyFallbackRequested || explicitReporter === undefined;
      if (minimalRushConfigurationJson) {
        configuration = new MinimalRushConfiguration(minimalRushConfigurationJson, rushJsonLocation);
        const currentPackageVersion: string = PackageJsonLookup.loadOwnPackageJson(__dirname).version;
        const effectiveRushVersion: string = getRushPreviewVersion() ?? configuration.rushVersion;
        legacyPresentation =
          legacyFallbackRequested ||
          (effectiveRushVersion !== currentPackageVersion && explicitReporter === undefined) ||
          (!configuration.useRushReporter && explicitReporter === undefined);
      }
      if (showVerbose && legacyPresentation) {
        // Preserve discovery even when the full engine must report a configuration load error.
        writeLine('Found configuration in ' + rushJsonLocation);
        writeLine('');
      }
      return configuration;
    } else {
      return undefined;
    }
  }

  /**
   * The version of rush specified by the rushVersion property of the rush.json configuration file. If the
   *  rushVersion property is not specified, this falls back to the rushMinimumVersion property. This should be
   *  a semver style version number like "4.0.0"
   */
  public get rushVersion(): string {
    return this.#rushVersion;
  }

  /**
   * The folder where Rush's additional config files are stored.  This folder is always a
   * subfolder called "config\rush" inside the common folder.  (The "common\config" folder
   * is reserved for configuration files used by other tools.)  To avoid confusion or mistakes,
   * Rush will report an error if this this folder contains any unrecognized files.
   *
   * Example: "C:\MyRepo\common\config\rush"
   */
  public get commonRushConfigFolder(): string {
    return this.#commonRushConfigFolder;
  }

  /**
   * Whether the repository explicitly opted in to the experimental Rush reporter frontend.
   */
  public get useRushReporter(): boolean {
    return this.#useRushReporter;
  }

  /**
   * The repository's common temp folder, used for invocation-scoped reporter logs.
   */
  public get commonTempFolder(): string {
    return (
      EnvironmentConfiguration._getRushTempFolderOverride(process.env) ??
      path.resolve(this.#commonRushConfigFolder, '..', '..', 'temp')
    );
  }
}

function _getExplicitReporter(argv: readonly string[]): ReporterName | undefined {
  for (let index: number = 0; index < argv.length; index++) {
    const argument: string = argv[index];
    if (argument === '--') {
      break;
    }
    let value: string | undefined;
    if (argument === '--reporter') {
      const nextArgument: string | undefined = argv[index + 1];
      if (!nextArgument || nextArgument.startsWith('-')) {
        continue;
      }
      value = nextArgument;
      index++;
    } else if (argument.startsWith('--reporter=')) {
      value = argument.slice('--reporter='.length);
    }
    if (value !== undefined) {
      const normalizedValue: string = value.trim().toLowerCase();
      return isSupportedReporterName(normalizedValue) ? normalizedValue : undefined;
    }
  }
  return undefined;
}

function _hasHelpControl(argv: readonly string[]): boolean {
  for (const argument of argv) {
    if (argument === '--') {
      return false;
    }
    if (argument === '--help' || argument === '-h') {
      return true;
    }
  }
  return false;
}

function _loadConfigurationJson(rushJsonFilename: string): IMinimalRushConfigurationJson | undefined {
  try {
    return JsonFile.load(rushJsonFilename);
  } catch (e) {
    return undefined;
  }
}

function _loadExperimentsConfigurationJson(
  experimentsJsonFilename: string
): IMinimalExperimentsConfigurationJson | undefined {
  try {
    return JsonFile.load(experimentsJsonFilename);
  } catch (e) {
    if (FileSystem.isNotExistError(e)) {
      return undefined;
    }
    throw e;
  }
}