Move .d.ts files from lib-commonjs to lib-dts in rush-lib and rush-sdk

iclanton · iclanton · commit 4a7bb3a1d69d · 2026-02-21T21:49:30.000-08:00
- Remove dTsFilesInputFolderName from DeepImportsPlugin config in rush-lib webpack
- Update copyEmptyModules.js to only generate JS stubs without .d.ts copying
- Refactor rush-sdk generate-stubs.ts to only create JS stubs
- Add copy-files-plugin task to copy .d.ts files from rush-lib/lib-dts to rush-sdk/lib-dts
- Declarations now live only in lib-dts, not duplicated in lib-commonjs
diff --git a/libraries/rush-lib/scripts/copyEmptyModules.js b/libraries/rush-lib/scripts/copyEmptyModules.js
@@ -3,7 +3,6 @@
 const { FileSystem, Async, AsyncQueue } = require('@rushstack/node-core-library');
 
 const JS_FILE_EXTENSION = '.js';
-const DTS_FILE_EXTENSION = '.d.ts';
 
 module.exports = {
   runAsync: async ({
@@ -15,17 +14,16 @@ module.exports = {
     // We're using a Webpack plugin called `@rushstack/webpack-deep-imports-plugin` to
     // examine all of the modules that are imported by the entrypoints (index, and the start* scripts)
     // to `rush-lib` and generate stub JS files in the `lib` folder that reference the original modules
-    // in the webpack bundle. The plugin also copies the `.d.ts` files for those modules to the `lib` folder.
+    // in the webpack bundle.
     //
     // A limitation of this approach is that only modules that contain runtime code end up in the Webpack
-    // bundle, so only modules that contain runtime code get stubs and have their `.d.ts` files copied. This
+    // bundle, so only modules that contain runtime code get stubs. This
     // creates a problem when a `.d.ts` file references a module that doesn't have runtime code (i.e. -
-    // a `.d.ts` file that only contains types).
+    // a `.ts` file that only contains types).
     //
     // This script looks through the `lib-intermediate-esm` folder for `.js` files that were produced by the TypeScript
     // compiler from `.ts` files that contain no runtime code and generates stub `.js` files for them in the
-    // `lib` folder and copies the corresponding `.d.ts` files to the `lib`. This ensures that the `.d.ts`
-    // files that end up in the `lib` folder don't have any unresolved imports. This is tested by the
+    // `lib-commonjs` folder. This ensures that all modules have corresponding JS stubs. This is tested by the
     // `rush-lib-declaration-paths-test` project in the `build-tests`
 
     function stripCommentsFromJsFile(jsFileText) {
@@ -44,7 +42,6 @@ module.exports = {
     }
 
     const jsInFolderPath = `${buildFolderPath}/lib-intermediate-esm`;
-    const dtsInFolderPath = `${buildFolderPath}/lib-dts`;
     const outCjsFolderPath = `${buildFolderPath}/lib-commonjs`;
     const emptyModuleBuffer = Buffer.from('module.exports = {};', 'utf8');
     const folderPathQueue = new AsyncQueue([undefined]);
@@ -70,15 +67,6 @@ module.exports = {
               await FileSystem.writeFileAsync(outJsPath, emptyModuleBuffer, {
                 ensureFolderExists: true
               });
-
-              const relativeDtsPath =
-                relativeItemPath.slice(0, -JS_FILE_EXTENSION.length) + DTS_FILE_EXTENSION;
-              const inDtsPath = `${dtsInFolderPath}/${relativeDtsPath}`;
-              const outDtsPath = `${outCjsFolderPath}/${relativeDtsPath}`;
-              terminal.writeVerboseLine(`Copying ${inDtsPath} to ${outDtsPath}`);
-              // We know this is a file, don't need the redundant checks in FileSystem.copyFileAsync
-              const buffer = await FileSystem.readFileToBufferAsync(inDtsPath);
-              await FileSystem.writeFileAsync(outDtsPath, buffer, { ensureFolderExists: true });
             }
           }
         }
diff --git a/libraries/rush-lib/webpack.config.js b/libraries/rush-lib/webpack.config.js
@@ -100,8 +100,7 @@ module.exports = () => {
           path: `${__dirname}/temp/build/webpack-dll/[name].json`,
           inFolderName: 'lib-intermediate-esm',
           outFolderName: 'lib-commonjs',
-          pathsToIgnore: ['utilities/prompts/SearchListPrompt.js'],
-          dTsFilesInputFolderName: 'lib-dts'
+          pathsToIgnore: ['utilities/prompts/SearchListPrompt.js']
         })
       ],
       {
diff --git a/libraries/rush-sdk/config/heft.json b/libraries/rush-sdk/config/heft.json
@@ -31,16 +31,18 @@
                   "sourcePath": "./node_modules/@microsoft/rush-lib/dist",
                   "includeGlobs": ["rush-lib.d.ts"],
                   "destinationFolders": ["dist"]
+                },
+                {
+                  "sourcePath": "./node_modules/@microsoft/rush-lib/lib-dts",
+                  "destinationFolders": ["lib-dts"],
+                  "fileExtensions": [".d.ts"],
+                  "hardlink": true
                 }
               ]
             }
           }
         },
 
-        "typescript": {
-          "taskDependencies": ["copy-rush-lib-types"]
-        },
-
         "webpack": {
           "taskDependencies": ["typescript"],
           "taskPlugin": {
@@ -49,7 +51,7 @@
         },
 
         "generate-stubs": {
-          "taskDependencies": ["typescript"],
+          "taskDependencies": ["typescript", "copy-rush-lib-types"],
           "taskPlugin": {
             "pluginPackage": "@rushstack/heft",
             "pluginName": "run-script-plugin",
diff --git a/libraries/rush-sdk/src/generate-stubs.ts b/libraries/rush-sdk/src/generate-stubs.ts
@@ -6,108 +6,89 @@ import * as path from 'node:path';
 import type { IRunScriptOptions } from '@rushstack/heft';
 import { Async, FileSystem, type FolderItem, Import, JsonFile, Path } from '@rushstack/node-core-library';
 
-interface IGenerateOptions {
+interface IGenerateJsStubsOptions {
   parentSourcePath: string;
-  parentCjsTargetPath: string;
-  parentDtsTargetPath: string;
+  parentTargetPath: string;
   parentSrcImportPathWithSlash: string;
   libShimIndexPath: string;
 }
 
-interface IFileTask {
-  type: 'dts' | 'js';
-  sourcePath: string;
+interface IJsStubTask {
+  jsSourcePath: string;
   targetPath: string;
-  srcImportPath?: string;
-  shimPathLiteral?: string;
+  srcImportPath: string;
+  shimPathLiteral: string;
 }
 
-async function* collectFileTasksAsync(options: IGenerateOptions): AsyncGenerator<IFileTask> {
-  const {
-    parentSourcePath,
-    parentCjsTargetPath,
-    parentDtsTargetPath,
-    parentSrcImportPathWithSlash,
-    libShimIndexPath
-  } = options;
-  const folderItems: FolderItem[] = await FileSystem.readFolderItemsAsync(options.parentSourcePath);
+/**
+ * Walks rush-lib/lib-commonjs to collect JS stub tasks. These stubs redirect
+ * require() calls through the rush-sdk shim so that the actual rush-lib module
+ * is loaded at runtime.
+ */
+async function* collectJsStubTasksAsync(options: IGenerateJsStubsOptions): AsyncGenerator<IJsStubTask> {
+  const { parentSourcePath, parentTargetPath, parentSrcImportPathWithSlash, libShimIndexPath } = options;
+  const folderItems: FolderItem[] = await FileSystem.readFolderItemsAsync(parentSourcePath);
 
   for (const folderItem of folderItems) {
     const itemName: string = folderItem.name;
     const sourcePath: string = `${parentSourcePath}/${itemName}`;
-    const cjsTargetPath: string = `${parentCjsTargetPath}/${itemName}`;
-    const dtsTargetPath: string = `${parentDtsTargetPath}/${itemName}`;
+    const targetPath: string = `${parentTargetPath}/${itemName}`;
 
     if (folderItem.isDirectory()) {
       // Ensure destination folder exists
-      await FileSystem.ensureFolderAsync(cjsTargetPath);
+      await FileSystem.ensureFolderAsync(targetPath);
       // Recursively yield tasks from subdirectory
-      yield* collectFileTasksAsync({
+      yield* collectJsStubTasksAsync({
         parentSourcePath: sourcePath,
-        parentCjsTargetPath: cjsTargetPath,
-        parentDtsTargetPath: dtsTargetPath,
+        parentTargetPath: targetPath,
         parentSrcImportPathWithSlash: parentSrcImportPathWithSlash + itemName + '/',
         libShimIndexPath
       });
-    } else if (folderItem.name.endsWith('.d.ts')) {
-      yield {
-        type: 'dts',
-        sourcePath,
-        targetPath: dtsTargetPath
-      };
     } else if (folderItem.name.endsWith('.js')) {
       const srcImportPath: string = parentSrcImportPathWithSlash + path.parse(folderItem.name).name;
-      const shimPath: string = path.relative(parentCjsTargetPath, libShimIndexPath);
+      const shimPath: string = path.relative(parentTargetPath, libShimIndexPath);
       const shimPathLiteral: string = JSON.stringify(Path.convertToSlashes(shimPath));
 
       yield {
-        type: 'js',
-        sourcePath,
-        targetPath: cjsTargetPath,
+        jsSourcePath: sourcePath,
+        targetPath,
         srcImportPath,
         shimPathLiteral
       };
     }
   }
 }
 
-async function processFileTaskAsync(task: IFileTask): Promise<void> {
-  const { type, sourcePath, targetPath, srcImportPath, shimPathLiteral } = task;
-  if (type === 'dts') {
-    await FileSystem.copyFileAsync({
-      sourcePath,
-      destinationPath: targetPath
-    });
-  } else {
-    const srcImportPathLiteral: string = JSON.stringify(srcImportPath);
-
-    let namedExportsAssignment: string = '';
-    try {
-      // Read the sidecar .exports.json file generated by DeepImportsPlugin to get module exports
-      const exportsJsonPath: string = sourcePath.slice(0, -'.js'.length) + '.exports.json';
-      const { moduleExports }: { moduleExports: string[] } = await JsonFile.loadAsync(exportsJsonPath);
-      if (moduleExports.length > 0) {
-        // Assign named exports after module.exports to ensure they're properly exposed for ESM imports
-        namedExportsAssignment =
-          '\n' + moduleExports.map((exportName) => `exports.${exportName} = _m.${exportName};`).join('\n');
-      }
-    } catch (e) {
-      if (!FileSystem.isNotExistError(e)) {
-        throw e;
-      }
+async function processJsStubTaskAsync(task: IJsStubTask): Promise<void> {
+  const { jsSourcePath, targetPath, srcImportPath, shimPathLiteral } = task;
+  const srcImportPathLiteral: string = JSON.stringify(srcImportPath);
+
+  let namedExportsAssignment: string = '';
+  try {
+    // Read the sidecar .exports.json file generated by DeepImportsPlugin to get module exports
+    const exportsJsonPath: string = jsSourcePath.slice(0, -'.js'.length) + '.exports.json';
+    const { moduleExports }: { moduleExports: string[] } = await JsonFile.loadAsync(exportsJsonPath);
+    if (moduleExports.length > 0) {
+      // Assign named exports after module.exports to ensure they're properly exposed for ESM imports
+      namedExportsAssignment =
+        '\n' + moduleExports.map((exportName) => `exports.${exportName} = _m.${exportName};`).join('\n');
+    }
+  } catch (e) {
+    if (!FileSystem.isNotExistError(e)) {
+      throw e;
     }
-
-    await FileSystem.writeFileAsync(
-      targetPath,
-      // Example:
-      // ```
-      // const _m = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/policy/GitEmailPolicy");
-      // module.exports = _m;
-      // exports.GitEmailPolicy = _m.GitEmailPolicy;
-      // ```
-      `const _m = require(${shimPathLiteral})._rushSdk_loadInternalModule(${srcImportPathLiteral});\nmodule.exports = _m;${namedExportsAssignment}\n`
-    );
   }
+
+  await FileSystem.writeFileAsync(
+    targetPath,
+    // Example:
+    // ```
+    // const _m = require("../../../lib-shim/index")._rushSdk_loadInternalModule("logic/policy/GitEmailPolicy");
+    // module.exports = _m;
+    // exports.GitEmailPolicy = _m.GitEmailPolicy;
+    // ```
+    `const _m = require(${shimPathLiteral})._rushSdk_loadInternalModule(${srcImportPathLiteral});\nmodule.exports = _m;${namedExportsAssignment}\n`
+  );
 }
 
 // Entry point invoked by "runScript" action from config/heft.json
@@ -126,23 +107,20 @@ export async function runAsync(options: IRunScriptOptions): Promise<void> {
   });
 
   const cjsStubsTargetPath: string = `${buildFolderPath}/lib-commonjs`;
-  const dtsStubsTargetPath: string = `${buildFolderPath}/lib-dts`;
-  terminal.writeLine(
-    `generate-stubs: Generating stub files under ${cjsStubsTargetPath} and ${dtsStubsTargetPath}`
-  );
+  terminal.writeLine(`generate-stubs: Generating stub files under ${cjsStubsTargetPath}`);
 
   // Ensure the target folder exists
   await FileSystem.ensureFolderAsync(cjsStubsTargetPath);
 
-  // Collect and process file tasks in parallel with controlled concurrency
-  const tasks: AsyncGenerator<IFileTask> = collectFileTasksAsync({
+  // Generate JS stubs from rush-lib/lib-commonjs (these redirect require() through the shim)
+  // Note: .d.ts files are copied separately by the copy-rush-lib-types heft task from rush-lib/lib-dts
+  const jsTasks: AsyncGenerator<IJsStubTask> = collectJsStubTasksAsync({
     parentSourcePath: `${rushLibFolder}/lib-commonjs`,
-    parentCjsTargetPath: cjsStubsTargetPath,
-    parentDtsTargetPath: dtsStubsTargetPath,
+    parentTargetPath: cjsStubsTargetPath,
     parentSrcImportPathWithSlash: '',
     libShimIndexPath: `${buildFolderPath}/lib-shim/index.js`
   });
-  await Async.forEachAsync(tasks, processFileTaskAsync, { concurrency: 50 });
+  await Async.forEachAsync(jsTasks, processJsStubTaskAsync, { concurrency: 50 });
 
   terminal.writeLine('generate-stubs: Completed successfully.');
 }
