[workspace-resolve-plugin] Create plugin for more efficient resolution when repo structure is known

README.md

@@ -105,6 +105,7 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/webpack/set-webpack-public-path-plugin](./webpack/set-webpack-public-path-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fset-webpack-public-path-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fset-webpack-public-path-plugin) | [changelog](./webpack/set-webpack-public-path-plugin/CHANGELOG.md) | [@rushstack/set-webpack-public-path-plugin](https://www.npmjs.com/package/@rushstack/set-webpack-public-path-plugin) |
 | [/webpack/webpack-embedded-dependencies-plugin](./webpack/webpack-embedded-dependencies-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fwebpack-embedded-dependencies-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fwebpack-embedded-dependencies-plugin) | [changelog](./webpack/webpack-embedded-dependencies-plugin/CHANGELOG.md) | [@rushstack/webpack-embedded-dependencies-plugin](https://www.npmjs.com/package/@rushstack/webpack-embedded-dependencies-plugin) |
 | [/webpack/webpack-plugin-utilities](./webpack/webpack-plugin-utilities/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fwebpack-plugin-utilities.svg)](https://badge.fury.io/js/%40rushstack%2Fwebpack-plugin-utilities) | [changelog](./webpack/webpack-plugin-utilities/CHANGELOG.md) | [@rushstack/webpack-plugin-utilities](https://www.npmjs.com/package/@rushstack/webpack-plugin-utilities) |
+| [/webpack/webpack-workspace-resolve-plugin](./webpack/webpack-workspace-resolve-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fwebpack-workspace-resolve-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fwebpack-workspace-resolve-plugin) | [changelog](./webpack/webpack-workspace-resolve-plugin/CHANGELOG.md) | [@rushstack/webpack-workspace-resolve-plugin](https://www.npmjs.com/package/@rushstack/webpack-workspace-resolve-plugin) |
 | [/webpack/webpack4-localization-plugin](./webpack/webpack4-localization-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fwebpack4-localization-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fwebpack4-localization-plugin) | [changelog](./webpack/webpack4-localization-plugin/CHANGELOG.md) | [@rushstack/webpack4-localization-plugin](https://www.npmjs.com/package/@rushstack/webpack4-localization-plugin) |
 | [/webpack/webpack4-module-minifier-plugin](./webpack/webpack4-module-minifier-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fwebpack4-module-minifier-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fwebpack4-module-minifier-plugin) | [changelog](./webpack/webpack4-module-minifier-plugin/CHANGELOG.md) | [@rushstack/webpack4-module-minifier-plugin](https://www.npmjs.com/package/@rushstack/webpack4-module-minifier-plugin) |
 | [/webpack/webpack5-load-themed-styles-loader](./webpack/webpack5-load-themed-styles-loader/) | [![npm version](https://badge.fury.io/js/%40microsoft%2Fwebpack5-load-themed-styles-loader.svg)](https://badge.fury.io/js/%40microsoft%2Fwebpack5-load-themed-styles-loader) | [changelog](./webpack/webpack5-load-themed-styles-loader/CHANGELOG.md) | [@microsoft/webpack5-load-themed-styles-loader](https://www.npmjs.com/package/@microsoft/webpack5-load-themed-styles-loader) |

common/changes/@rushstack/webpack-workspace-resolve-plugin/workspace-resolve-plugin_2024-08-12-19-12.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/webpack-workspace-resolve-plugin",
+      "comment": "Add plugin for more efficient import resolution in a monorepo with known structure. Optimizes lookup of the relevant `package.json` for a given path, and lookup of npm dependencies of the containing package.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/webpack-workspace-resolve-plugin"
+}

common/reviews/api/webpack-workspace-resolve-plugin.api.md

@@ -0,0 +1,65 @@
+## API Report File for "@rushstack/webpack-workspace-resolve-plugin"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { Compiler } from 'webpack';
+import { IPrefixMatch } from '@rushstack/lookup-by-path';
+import { LookupByPath } from '@rushstack/lookup-by-path';
+import type { WebpackPluginInstance } from 'webpack';
+
+// @beta
+export interface IResolveContext {
+    descriptionFileRoot: string;
+    findDependency(request: string): IPrefixMatch<IResolveContext> | undefined;
+}
+
+// @beta
+export interface IResolverCacheFile {
+    contexts: ISerializedResolveContext[];
+}
+
+// @beta
+export interface ISerializedResolveContext {
+    deps: Record<string, number>;
+    dirInfoFiles?: string[];
+    name: string;
+    root: string;
+}
+
+// @beta
+export interface IWorkspaceLayoutCacheOptions {
+    cacheData: IResolverCacheFile;
+    resolverPathSeparator?: '/' | '\\';
+    workspaceRoot: string;
+}
+
+// @beta
+export interface IWorkspaceResolvePluginOptions {
+    cache: WorkspaceLayoutCache;
+}
+
+// @beta
+export class WorkspaceLayoutCache {
+    constructor(options: IWorkspaceLayoutCacheOptions);
+    readonly contextForPackage: WeakMap<object, IResolveContext>;
+    readonly contextLookup: LookupByPath<IResolveContext>;
+    // (undocumented)
+    readonly normalizeToPlatform: (input: string) => string;
+    // (undocumented)
+    readonly normalizeToSlash: (input: string) => string;
+    // (undocumented)
+    readonly resolverPathSeparator: string;
+}
+
+// @beta
+export class WorkspaceResolvePlugin implements WebpackPluginInstance {
+    constructor(cache: WorkspaceLayoutCache);
+    // (undocumented)
+    apply(compiler: Compiler): void;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```

rush.json

@@ -1275,6 +1275,12 @@
       "reviewCategory": "libraries",
       "shouldPublish": false // for now
     },
+    {
+      "packageName": "@rushstack/webpack-workspace-resolve-plugin",
+      "projectFolder": "webpack/webpack-workspace-resolve-plugin",
+      "reviewCategory": "libraries",
+      "shouldPublish": true
+    },
     {
       "packageName": "@rushstack/set-webpack-public-path-plugin",
       "projectFolder": "webpack/set-webpack-public-path-plugin",

webpack/webpack-workspace-resolve-plugin/.eslintrc.js

@@ -0,0 +1,12 @@
+// This is a workaround for https://github.com/eslint/eslint/issues/3458
+require('local-node-rig/profiles/default/includes/eslint/patch/modern-module-resolution');
+// This is a workaround for https://github.com/microsoft/rushstack/issues/3021
+require('local-node-rig/profiles/default/includes/eslint/patch/custom-config-package-names');
+
+module.exports = {
+  extends: [
+    'local-node-rig/profiles/default/includes/eslint/profile/node-trusted-tool',
+    'local-node-rig/profiles/default/includes/eslint/mixins/friendly-locals'
+  ],
+  parserOptions: { tsconfigRootDir: __dirname }
+};

webpack/webpack-workspace-resolve-plugin/.npmignore

@@ -0,0 +1,32 @@
+# THIS IS A STANDARD TEMPLATE FOR .npmignore FILES IN THIS REPO.
+
+# Ignore all files by default, to avoid accidentally publishing unintended files.
+*
+
+# Use negative patterns to bring back the specific things we want to publish.
+!/bin/**
+!/lib/**
+!/lib-*/**
+!/dist/**
+
+!CHANGELOG.md
+!CHANGELOG.json
+!heft-plugin.json
+!rush-plugin-manifest.json
+!ThirdPartyNotice.txt
+
+# Ignore certain patterns that should not get published.
+/dist/*.stats.*
+/lib/**/test/
+/lib-*/**/test/
+*.test.js
+
+# NOTE: These don't need to be specified, because NPM includes them automatically.
+#
+# package.json
+# README.md
+# LICENSE
+
+# ---------------------------------------------------------------------------
+# DO NOT MODIFY ABOVE THIS LINE!  Add any project-specific overrides below.
+# ---------------------------------------------------------------------------

webpack/webpack-workspace-resolve-plugin/LICENSE

@@ -0,0 +1,24 @@
+@rushstack/webpack-workspace-resolve-plugin
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

webpack/webpack-workspace-resolve-plugin/README.md

@@ -0,0 +1,35 @@
+# @rushstack/webpack-workspace-resolve-plugin
+
+This package contains a plugin for webpack 5 that leverages a cache file generated from package manager metadata to greatly accelerate module resolution.
+Local benchmarks have shown a savings of around 10% of build time for some fairly large closed source projects.
+
+## Installation
+
+`npm install @rushstack/webpack-workspace-resolve-plugin --save-dev`
+
+## Overview
+
+This plugin is intended primarily for use in pnpm monorepos, but any tool that produces a strict package layout can be made compatible by generating the necessary cache file.
+
+The cache file contains information about the locations of every `package.json` file known to the package manager (including those in subdirectories of packages), as well as the list of declared dependencies of each and where they can be found.
+
+When using this plugin, the following options should be configured for your resolver:
+- `symlinks: false` - Since the cache knows the symlinks for package dependencies, you can avoid the cost of testing for other symlinks unless you are using additional symlinks.
+- `modules: []` - The cache should contain all information necessary to locate available dependencies for any arbitrary folder. If you need to allow resolution in other roots, you can add those, but omit `'node_modules'`.
+
+## Limitations
+
+This plugin depends on the presence of a cache file in the workspace to function. Data in this cache file is assumed not to change while the webpack process is running, although the file will be.
+
+**Note:** Generating the cache file is not in the scope of this plugin.
+
+This plugin does not currently support having subdirectory `package.json` files within workspace projects (e.g. for declaring `{ "type": "module" }` in mixed CommonJS/ESM packages).
+This plugin does not work (well) with a hoisted node_modules installation layout.
+
+## Links
+
+- [CHANGELOG.md](
+  https://github.com/microsoft/rushstack/blob/main/webpack/webpack-workspace-resolve-plugin/CHANGELOG.md) - Find
+  out what's new in the latest version
+
+`@rushstack/webpack5-workspace-resolve-plugin` is part of the [Rush Stack](https://rushstack.io/) family of projects.

webpack/webpack-workspace-resolve-plugin/config/api-extractor.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "../../../common/reviews/api"
+  },
+
+  "docModel": {
+    "enabled": false,
+    "apiJsonFilePath": "../../../common/temp/api/<unscopedPackageName>.api.json"
+  },
+
+  "dtsRollup": {
+    "enabled": true
+  }
+}

webpack/webpack-workspace-resolve-plugin/config/jest.config.json

@@ -0,0 +1,3 @@
+{
+  "extends": "local-node-rig/profiles/default/config/jest.config.json"
+}

webpack/webpack-workspace-resolve-plugin/config/rig.json

@@ -0,0 +1,7 @@
+{
+  // The "rig.json" file directs tools to look for their config files in an external package.
+  // Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+
+  "rigPackageName": "local-node-rig"
+}

webpack/webpack-workspace-resolve-plugin/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@rushstack/webpack-workspace-resolve-plugin",
+  "version": "0.0.0",
+  "description": "This plugin leverages workspace-level metadata to greatly accelerate module resolution.",
+  "main": "lib/index.js",
+  "typings": "dist/webpack-workspace-resolve-plugin.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/rushstack.git",
+    "directory": "webpack/webpack-workspace-resolve-plugin"
+  },
+  "engines": {
+    "node": ">=18.19.0"
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean"
+  },
+  "peerDependencies": {
+    "webpack": "^5.68.0",
+    "@types/node": "*"
+  },
+  "dependencies": {
+    "@rushstack/lookup-by-path": "workspace:*",
+    "@types/tapable": "1.0.6",
+    "tapable": "2.2.1"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "workspace:*",
+    "local-node-rig": "workspace:*",
+    "memfs": "3.4.3",
+    "webpack": "~5.82.1"
+  },
+  "sideEffects": false,
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
+  }
+}