[rush] Subspace Configuration Files

common/changes/@microsoft/rush/will-intro-subspace_2023-12-04-16-28.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add subspace configuration file structure",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

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

@@ -1051,6 +1051,7 @@ export class RushConfiguration {
     readonly commonRushConfigFolder: string;
     readonly commonScriptsFolder: string;
     readonly commonTempFolder: string;
+    readonly commonTempSubspaceFolderRoot: string;
     // @deprecated
     get commonVersions(): CommonVersionsConfiguration;
     get currentInstalledVariant(): string | undefined;
@@ -1082,6 +1083,7 @@ export class RushConfiguration {
     readonly gitSampleEmail: string;
     readonly gitTagSeparator: string | undefined;
     readonly gitVersionBumpCommitMessage: string | undefined;
+    get hasSubspaces(): boolean;
     readonly hotfixChangeEnabled: boolean;
     static loadFromConfigurationFile(rushJsonFilename: string): RushConfiguration;
     // (undocumented)
@@ -1122,11 +1124,17 @@ export class RushConfiguration {
     readonly _rushPluginsConfiguration: RushPluginsConfiguration;
     readonly shrinkwrapFilename: string;
     get shrinkwrapFilePhrase(): string;
+    // Warning: (ae-forgotten-export) The symbol "SubspaceConfiguration" needs to be exported by the entry point index.d.ts
+    readonly subspaceConfiguration?: SubspaceConfiguration;
+    // (undocumented)
+    get subspaceNames(): string[];
+    readonly subspaceShrinkwrapFilenames: (subspaceName: string) => string;
     readonly suppressNodeLtsWarning: boolean;
     // @beta
     readonly telemetryEnabled: boolean;
     readonly tempShrinkwrapFilename: string;
     readonly tempShrinkwrapPreinstallFilename: string;
+    readonly tempSubspaceShrinkwrapFileName: (subspaceName: string) => string;
     static tryFindRushJsonLocation(options?: ITryFindRushJsonLocationOptions): string | undefined;
     tryGetProjectForPath(currentFolderPath: string): RushConfigurationProject | undefined;
     // (undocumented)
@@ -1169,6 +1177,7 @@ export class RushConfigurationProject {
     readonly rushConfiguration: RushConfiguration;
     get shouldPublish(): boolean;
     readonly skipRushCheck: boolean;
+    readonly subspace?: string;
     // @beta
     readonly tags: ReadonlySet<string>;
     readonly tempProjectName: string;

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

@@ -42,6 +42,7 @@ import schemaJson from '../schemas/rush.schema.json';
 import type * as DependencyAnalyzerModuleType from '../logic/DependencyAnalyzer';
 import type { PackageManagerOptionsConfigurationBase } from '../logic/base/BasePackageManagerOptionsConfiguration';
 import { CustomTipsConfiguration } from './CustomTipsConfiguration';
+import { SubspaceConfiguration } from './SubspaceConfiguration';
 
 const MINIMUM_SUPPORTED_RUSH_JSON_VERSION: string = '0.0.0';
 const DEFAULT_BRANCH: string = 'main';
@@ -186,6 +187,16 @@ export interface ICurrentVariantJson {
   variant: string | JsonNull;
 }
 
+/**
+ * The filter parameters to search from all projects
+ */
+export interface IRushConfigurationProjectsFilter {
+  /**
+   * A string representation of the subspace to filter for
+   */
+  subspace: string;
+}
+
 /**
  * Options for `RushConfiguration.tryFindRushJsonLocation`.
  * @public
@@ -222,6 +233,11 @@ export class RushConfiguration {
   // Lazily loaded when the projectsByTag() getter is called.
   private _projectsByTag: ReadonlyMap<string, ReadonlySet<RushConfigurationProject>> | undefined;
 
+  // Cache subspace projects
+  private _subspaceProjectsCache: Map<string, RushConfigurationProject[]>;
+
+  private _hasSubspaces: boolean | undefined;
+
   // variant -> common-versions configuration
   private _commonVersionsConfigurationsByVariant: Map<string, CommonVersionsConfiguration> | undefined;
 
@@ -287,6 +303,14 @@ export class RushConfiguration {
    */
   public readonly commonTempFolder: string;
 
+  /**
+   * The folder where temporary files will be stored for subspaces. The specific folder will
+   * append the subspace name to this path.
+   *
+   * Example: `C:\MyRepo\common\temp\<subspace_name>`
+   */
+  public readonly commonTempSubspaceFolderRoot: string;
+
   /**
    * The folder where automation scripts are stored.  This is always a subfolder called "scripts"
    * under the common folder.
@@ -348,6 +372,30 @@ export class RushConfiguration {
    */
   public readonly tempShrinkwrapPreinstallFilename: string;
 
+  /**
+   * The object that specifies subspace configurations if they are provided in the rush workspace.
+   */
+  public readonly subspaceConfiguration?: SubspaceConfiguration;
+
+  /**
+   * The filename (without any path) of the shrinkwrap file used for individual subspaces, used by the package manager.
+   * @remarks
+   * This property merely reports the filename; The file itself may not actually exist.
+   * Example: `pnpm-lock.yaml`
+   */
+  public readonly subspaceShrinkwrapFilenames: (subspaceName: string) => string;
+
+  /**
+   * The full path of the temporary shrinkwrap file for a specific subspace.
+   * This function takes the subspace name, and returns the full path for the subspace's shrinkwrap file.
+   * This function also consults the depreciated option to allow for shrinkwraps to be stored under a package folder.
+   * This shrinkwrap file is used during "rush install", and may be rewritten by the package manager during installation
+   * @remarks
+   * This property merely reports the filename, the file itself may not actually exist.
+   * example: `C:\MyRepo\common\<subspace_name>\pnpm-lock.yaml`
+   */
+  public readonly tempSubspaceShrinkwrapFileName: (subspaceName: string) => string;
+
   /**
    * The filename of the variant dependency data file.  By default this is
    * called 'current-variant.json' resides in the Rush common folder.
@@ -608,6 +656,8 @@ export class RushConfiguration {
       EnvironmentConfiguration.rushTempFolderOverride ||
       path.join(this.commonFolder, RushConstants.rushTempFolderName);
 
+    this.commonTempSubspaceFolderRoot = path.join(this.commonFolder, RushConstants.rushTempFolderName);
+
     this.commonScriptsFolder = path.join(this.commonFolder, 'scripts');
 
     this.npmCacheFolder = path.resolve(path.join(this.commonTempFolder, 'npm-cache'));
@@ -622,6 +672,15 @@ export class RushConfiguration {
 
     this.ensureConsistentVersions = !!rushConfigurationJson.ensureConsistentVersions;
 
+    // Check if we have a subspace configuration file
+    const subspaceConfigLocation: string = path.join(this.rushJsonFolder, 'subspaces.json');
+    if (FileSystem.exists(subspaceConfigLocation)) {
+      // Try getting a subspace configuration
+      this.subspaceConfiguration = SubspaceConfiguration.loadFromConfigurationFile(subspaceConfigLocation);
+    }
+
+    this._subspaceProjectsCache = new Map<string, RushConfigurationProject[]>();
+
     const experimentsConfigFile: string = path.join(
       this.commonRushConfigFolder,
       RushConstants.experimentsFilename
@@ -703,6 +762,15 @@ export class RushConfiguration {
 
     this.shrinkwrapFilename = this.packageManagerWrapper.shrinkwrapFilename;
 
+    // From "pnpm-lock.yaml" --> "subspace-pnpm-lock.yaml"
+    this.subspaceShrinkwrapFilenames = (subspaceName: string): string => {
+      const shrinkwrapFilenameParsedPath: path.ParsedPath = path.parse(this.shrinkwrapFilename);
+      return path.join(
+        shrinkwrapFilenameParsedPath.dir,
+        `${subspaceName}-` + shrinkwrapFilenameParsedPath.name + shrinkwrapFilenameParsedPath.ext
+      );
+    };
+
     this.tempShrinkwrapFilename = path.join(this.commonTempFolder, this.shrinkwrapFilename);
     this.packageManagerToolFilename = path.resolve(
       path.join(
@@ -714,6 +782,16 @@ export class RushConfiguration {
       )
     );
 
+    this.tempSubspaceShrinkwrapFileName = (subspaceName: string): string => {
+      // TODO: do subspace name validation here
+      const fullSubspacePath: string = path.join(
+        this.commonTempSubspaceFolderRoot,
+        subspaceName,
+        this.shrinkwrapFilename
+      );
+      return fullSubspacePath;
+    };
+
     /// From "C:\repo\common\temp\pnpm-lock.yaml" --> "C:\repo\common\temp\pnpm-lock-preinstall.yaml"
     const parsedPath: path.ParsedPath = path.parse(this.tempShrinkwrapFilename);
     this.tempShrinkwrapPreinstallFilename = path.join(
@@ -880,6 +958,14 @@ export class RushConfiguration {
         );
       }
       this._projectsByName.set(project.packageName, project);
+      if (projectJson.subspace) {
+        const subspaceName: string = projectJson.subspace;
+        if (this._subspaceProjectsCache.has(subspaceName)) {
+          (this._subspaceProjectsCache.get(subspaceName) as RushConfigurationProject[]).push(project);
+        } else {
+          this._subspaceProjectsCache.set(subspaceName, [project]);
+        }
+      }
     }
 
     for (const project of this._projects) {
@@ -1091,7 +1177,11 @@ export class RushConfiguration {
 
       // If the package manager is pnpm, then also add the pnpm file to the known set.
       if (packageManagerWrapper.packageManager === 'pnpm') {
-        knownSet.add((packageManagerWrapper as PnpmPackageManager).pnpmfileFilename.toUpperCase());
+        const pnpmPackageManager: PnpmPackageManager = packageManagerWrapper as PnpmPackageManager;
+        knownSet.add(pnpmPackageManager.pnpmfileFilename.toUpperCase());
+        // for (const subspaceName of this.subspaceNames()) {
+        //   knownSet.add(pnpmPackageManager.subspacePnpmfileFilename(subspaceName).toUpperCase());
+        // }
       }
 
       // Is the filename something we know?  If not, report an error.
@@ -1188,6 +1278,13 @@ export class RushConfiguration {
     return this._projects!;
   }
 
+  public get subspaceNames(): string[] {
+    if (!this._projects) {
+      this._initializeAndValidateLocalProjects();
+    }
+    return Array.from(this._subspaceProjectsCache.keys());
+  }
+
   public get projectsByName(): Map<string, RushConfigurationProject> {
     if (!this._projectsByName) {
       this._initializeAndValidateLocalProjects();
@@ -1262,6 +1359,16 @@ export class RushConfiguration {
     return commonVersionsFilename;
   }
 
+  /**
+   * Does this project have subspaces
+   */
+  public get hasSubspaces(): boolean {
+    if (undefined === this._hasSubspaces) {
+      this._hasSubspaces = this._subspaceProjectsCache.size > 0;
+    }
+    return this._hasSubspaces;
+  }
+
   /**
    * Gets the settings from the common-versions.json config file for a specific variant.
    * @param variant - The name of the current variant in use by the active command.

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

@@ -27,6 +27,7 @@ export interface IRushConfigurationProjectJson {
   skipRushCheck?: boolean;
   publishFolder?: string;
   tags?: string[];
+  subspace?: string;
 }
 
 /**
@@ -184,6 +185,11 @@ export class RushConfigurationProject {
    */
   public readonly tags: ReadonlySet<string>;
 
+  /**
+   * If this project is in a subspace, and which one
+   */
+  public readonly subspace?: string;
+
   /** @internal */
   public constructor(options: IRushConfigurationProjectOptions) {
     const { projectJson, rushConfiguration, tempProjectName, allowedProjectTags } = options;
@@ -324,6 +330,8 @@ export class RushConfigurationProject {
     } else {
       this.tags = new Set(projectJson.tags);
     }
+
+    this.subspace = projectJson.subspace;
   }
 
   /**

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

@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { JsonFile } from '@rushstack/node-core-library';
+import path from 'path';
+import { trueCasePathSync } from 'true-case-path';
+import { RushConfiguration } from './RushConfiguration';
+
+export interface ISubspaceConfig {
+  subspaceName: string;
+}
+
+/**
+ * This represents the JSON data structure for the "subspace.json" configuration file.
+ * See subspace.schema.json for documentation.
+ */
+export interface ISubspaceConfigurationJson {
+  $schema: string;
+  enabled: boolean;
+  depreciatedTTSupport?: boolean;
+  availableSubspaces: ISubspaceConfig;
+}
+
+export class SubspaceConfiguration {
+  /**
+   * The absolute path to the "subspace.json" configuration file that was loaded to construct this object.
+   */
+  public readonly subspaceJsonFile: string;
+
+  /**
+   * Gets the JSON data structure for the "subspace.json" configuration file.
+   *
+   * @internal
+   */
+  public readonly subspaceConfigurationJson: ISubspaceConfigurationJson;
+
+  /**
+   * A set of the available subspaces
+   */
+  public readonly availableSubspaceSet: Set<string>;
+
+  private constructor(subspaceConfigurationJson: ISubspaceConfigurationJson, subspaceJsonFilename: string) {
+    this.subspaceConfigurationJson = subspaceConfigurationJson;
+    this.subspaceJsonFile = subspaceJsonFilename;
+    this.availableSubspaceSet = new Set();
+
+    for (const { subspaceName } of Object.values(subspaceConfigurationJson.availableSubspaces)) {
+      this.availableSubspaceSet.add(subspaceName);
+    }
+  }
+
+  public static loadFromConfigurationFile(subspaceJsonFilename: string): SubspaceConfiguration {
+    let resolvedSubspaceJsonFilename: string = path.resolve(subspaceJsonFilename);
+
+    const subspaceConfigurationJson: ISubspaceConfigurationJson = JsonFile.load(resolvedSubspaceJsonFilename);
+
+    try {
+      resolvedSubspaceJsonFilename = trueCasePathSync(resolvedSubspaceJsonFilename);
+    } catch (error) {
+      /* ignore errors from true-case-path */
+    }
+
+    return new SubspaceConfiguration(subspaceConfigurationJson, resolvedSubspaceJsonFilename);
+  }
+
+  public static loadFromDefaultLocation(): SubspaceConfiguration | undefined {
+    const rushJsonLocation: string | undefined = RushConfiguration.tryFindRushJsonLocation();
+    if (rushJsonLocation) {
+      const subspaceJsonLocation: string = path.join(path.dirname(rushJsonLocation), 'subspace.json');
+      return SubspaceConfiguration.loadFromConfigurationFile(subspaceJsonLocation);
+    }
+  }
+}

libraries/rush-lib/src/api/packageManager/PnpmPackageManager.ts

@@ -22,6 +22,14 @@ export class PnpmPackageManager extends PackageManager {
    */
   public readonly pnpmfileFilename: string;
 
+  /**
+   * The filename of the shrinkwrap file of a subspace that is used by the package manager
+   *
+   * @remarks
+   * Example: `.pnpmfile-<subspace_name>.cjs
+   */
+  public subspacePnpmfileFilename: (subspaceName: string) => string;
+
   /** @internal */
   public constructor(version: string) {
     super(version, 'pnpm', RushConstants.pnpmV3ShrinkwrapFilename);
@@ -35,6 +43,10 @@ export class PnpmPackageManager extends PackageManager {
       this.pnpmfileFilename = RushConstants.pnpmfileV1Filename;
     }
 
+    this.subspacePnpmfileFilename = (subspaceName: string) => {
+      return `.pnpmfile-${subspaceName}.cjs`;
+    };
+
     // node_modules/.pnpm/lock.yaml
     // See https://github.com/pnpm/pnpm/releases/tag/v4.0.0 for more details.
     this.internalShrinkwrapRelativePath = path.join('node_modules', '.pnpm', 'lock.yaml');

libraries/rush-lib/src/schemas/rush.schema.json

@@ -307,6 +307,10 @@
               "type": "string",
               "pattern": "^[a-z0-9.@]+([-/][a-z0-9.@]+)*$"
             }
+          },
+          "subspace": {
+            "description": "An optional entry for specifying which subspace this project belongs to if the subspaces feature is enabled.",
+            "type": "string"
           }
         },
         "additionalProperties": false,