nx 21.0.0-beta.0 → 21.0.0-beta.10

package/src/plugins/js/lock-file/yarn-parser.js

@@ -29,14 +29,14 @@ function getYarnLockfileNodes(lockFileContent, lockFileHash, packageJson) {
     const isBerry = !!__metadata;
     // yarn classic splits keys when parsing so we need to stich them back together
     const groupedDependencies = groupDependencies(dependencies, isBerry);
-    return getNodes(groupedDependencies, packageJson, keyMap, isBerry);
+    return getNodes(groupedDependencies, packageJson, isBerry);
 }
 function getYarnLockfileDependencies(lockFileContent, lockFileHash, ctx) {
     const { __metadata, ...dependencies } = parseLockFile(lockFileContent, lockFileHash);
     const isBerry = !!__metadata;
     // yarn classic splits keys when parsing so we need to stich them back together
     const groupedDependencies = groupDependencies(dependencies, isBerry);
-    return getDependencies(groupedDependencies, keyMap, ctx);
+    return getDependencies(groupedDependencies, ctx);
 }
 function getPackageNameKeyPairs(keys) {
     const result = new Map();
@@ -51,7 +51,7 @@ function getPackageNameKeyPairs(keys) {
     });
     return result;
 }
-function getNodes(dependencies, packageJson, keyMap, isBerry) {
+function getNodes(dependencies, packageJson, isBerry) {
     const nodes = new Map();
     const combinedDeps = {
         ...packageJson.dependencies,
@@ -68,7 +68,7 @@ function getNodes(dependencies, packageJson, keyMap, isBerry) {
         nameKeyPairs.forEach((keySet, packageName) => {
             const keysArray = Array.from(keySet);
             // use key relevant to the package name
-            const version = findVersion(packageName, keysArray[0], snapshot, isBerry);
+            const [version, isAlias] = findVersion(packageName, keysArray[0], snapshot, isBerry);
             // use keys linked to the extracted package name
             keysArray.forEach((key) => {
                 // we don't need to keep duplicates, we can just track the keys
@@ -79,7 +79,7 @@ function getNodes(dependencies, packageJson, keyMap, isBerry) {
                 }
                 const node = {
                     type: 'npm',
-                    name: version
+                    name: version && !isAlias
                         ? `npm:${packageName}@${version}`
                         : `npm:${packageName}`,
                     data: {
@@ -151,7 +151,7 @@ function findVersion(packageName, key, snapshot, isBerry) {
         ? snapshot.resolution && !snapshot.resolution.startsWith(`${packageName}@`)
         : versionRange.startsWith('npm:');
     if (isAlias) {
-        return versionRange;
+        return [versionRange, true];
     }
     // check for berry tarball packages
     if (isBerry &&
@@ -159,13 +159,13 @@ function findVersion(packageName, key, snapshot, isBerry) {
         // different registry would yield suffix following '::' which we don't need
         snapshot.resolution.split('::')[0] !==
             `${packageName}@npm:${snapshot.version}`) {
-        return snapshot.resolution.slice(packageName.length + 1);
+        return [snapshot.resolution.slice(packageName.length + 1)];
     }
     if (!isBerry && isTarballPackage(versionRange, snapshot)) {
-        return snapshot.resolved;
+        return [snapshot.resolved];
     }
     // otherwise it's a standard version
-    return snapshot.version;
+    return [snapshot.version];
 }
 // check if snapshot represents tarball package
 function isTarballPackage(versionRange, snapshot) {
@@ -193,7 +193,7 @@ function getHoistedVersion(packageName) {
         return version;
     }
 }
-function getDependencies(dependencies, keyMap, ctx) {
+function getDependencies(dependencies, ctx) {
     const projectGraphDependencies = [];
     Object.keys(dependencies).forEach((keys) => {
         const snapshot = dependencies[keys];
@@ -203,8 +203,26 @@ function getDependencies(dependencies, keyMap, ctx) {
                 [snapshot.dependencies, snapshot.optionalDependencies].forEach((section) => {
                     if (section) {
                         Object.entries(section).forEach(([name, versionRange]) => {
-                            const target = keyMap.get(`${name}@npm:${versionRange}`) ||
+                            let target = keyMap.get(`${name}@npm:${versionRange}`) ||
                                 keyMap.get(`${name}@${versionRange}`);
+                            if (!target) {
+                                const shortRange = versionRange.replace(/^npm:/, '');
+                                // for range like 'npm:*' the above will not be a match
+                                if (shortRange === '*') {
+                                    const foundKey = Array.from(keyMap.keys()).find((k) => k.startsWith(`${name}@`));
+                                    if (foundKey) {
+                                        target = keyMap.get(foundKey);
+                                    }
+                                }
+                                else if (shortRange.includes('||')) {
+                                    // when range is a union of ranges, we need to treat it as an array
+                                    const ranges = shortRange.split('||').map((r) => r.trim());
+                                    target = Object.values(keyMap).find((n) => {
+                                        return (n.data.packageName === name &&
+                                            ranges.some((r) => (0, semver_1.satisfies)(n.data.version, r)));
+                                    })?.[1];
+                                }
+                            }
                             if (target) {
                                 const dep = {
                                     source: node.name,
@@ -271,11 +289,11 @@ function addPackageVersion(packageName, version, collection, isBerry) {
         collection.set(packageName, new Set());
     }
     collection.get(packageName).add(`${packageName}@${version}`);
-    if (isBerry && !version.startsWith('npm:')) {
+    if (isBerry && !version.startsWith('npm:') && !version.startsWith('patch:')) {
         collection.get(packageName).add(`${packageName}@npm:${version}`);
     }
 }
-function mapSnapshots(dependencies, nodes, packageJson, isBerry) {
+function mapSnapshots(rootDependencies, nodes, packageJson, isBerry) {
     // map snapshot to set of keys (e.g. `eslint@^7.0.0, eslint@npm:^7.0.0`)
     const snapshotMap = new Map();
     // track all existing dependencies's keys
@@ -286,8 +304,11 @@ function mapSnapshots(dependencies, nodes, packageJson, isBerry) {
         ...packageJson.optionalDependencies,
         ...packageJson.peerDependencies,
     };
+    const resolutions = {
+        ...packageJson.resolutions,
+    };
     // yarn classic splits keys when parsing so we need to stich them back together
-    const groupedDependencies = groupDependencies(dependencies, isBerry);
+    const groupedDependencies = groupDependencies(rootDependencies, isBerry);
     // collect snapshots and their matching keys
     Object.values(nodes).forEach((node) => {
         const foundOriginalKeys = findOriginalKeys(groupedDependencies, node);
@@ -311,9 +332,19 @@ function mapSnapshots(dependencies, nodes, packageJson, isBerry) {
                 snapshotMap.get(snapshot).add(requestedKey);
             }
         }
+        const requestedResolutionsVersion = getPackageJsonVersion(resolutions, node);
+        if (requestedResolutionsVersion) {
+            addPackageVersion(node.data.packageName, requestedResolutionsVersion, existingKeys, isBerry);
+            const requestedKey = isBerry
+                ? reverseMapBerryKey(node, requestedResolutionsVersion, snapshot)
+                : `${node.data.packageName}@${requestedResolutionsVersion}`;
+            if (!snapshotMap.get(snapshot).has(requestedKey)) {
+                snapshotMap.get(snapshot).add(requestedKey);
+            }
+        }
         if (isBerry) {
             // look for patched versions
-            const patch = findPatchedKeys(groupedDependencies, node);
+            const patch = findPatchedKeys(groupedDependencies, node, resolutions[node.data.packageName]);
             if (patch) {
                 const [matchedKeys, snapshot] = patch;
                 snapshotMap.set(snapshot, new Set(matchedKeys));
@@ -321,7 +352,7 @@ function mapSnapshots(dependencies, nodes, packageJson, isBerry) {
         }
     });
     // remove keys that match version ranges that have been pruned away
-    snapshotMap.forEach((snapshotValue, snapshotKey) => {
+    snapshotMap.forEach((snapshotValue, snapshot) => {
         for (const key of snapshotValue.values()) {
             const packageName = key.slice(0, key.indexOf('@', 1));
             let normalizedKey = key;
@@ -353,8 +384,8 @@ function mapSnapshots(dependencies, nodes, packageJson, isBerry) {
 }
 function reverseMapBerryKey(node, version, snapshot) {
     // alias packages already have version
-    if (version.startsWith('npm:')) {
-        `${node.data.packageName}@${version}`;
+    if (version.startsWith('npm:') || version.startsWith('patch:')) {
+        return `${node.data.packageName}@${version}`;
     }
     // check for berry tarball packages
     if (snapshot.resolution &&
@@ -363,15 +394,28 @@ function reverseMapBerryKey(node, version, snapshot) {
     }
     return `${node.data.packageName}@npm:${version}`;
 }
-function getPackageJsonVersion(combinedDependencies, node) {
+function getPackageJsonVersion(dependencies, node) {
     const { packageName, version } = node.data;
-    if (combinedDependencies[packageName]) {
-        if (combinedDependencies[packageName] === version ||
-            (0, semver_1.satisfies)(version, combinedDependencies[packageName])) {
-            return combinedDependencies[packageName];
+    if (dependencies[packageName]) {
+        const patchRegex = new RegExp(`^patch:${packageName}@(.*)|#.*$`);
+        // extract the version from the patch or use the full version
+        const versionRange = dependencies[packageName].match(patchRegex)?.[1] ||
+            dependencies[packageName];
+        if (versionRange === version || (0, semver_1.satisfies)(version, versionRange)) {
+            return dependencies[packageName];
         }
     }
 }
+function isStandardPackage(snapshot, version) {
+    return snapshot.version === version;
+}
+function isBerryAlias(snapshot, version) {
+    return snapshot.resolution && `npm:${snapshot.resolution}` === version;
+}
+function isClassicAlias(node, keys) {
+    return (node.data.version.startsWith('npm:') &&
+        keys.some((k) => k === `${node.data.packageName}@${node.data.version}`));
+}
 function findOriginalKeys(dependencies, node) {
     for (const keyExpr of Object.keys(dependencies)) {
         const snapshot = dependencies[keyExpr];
@@ -379,18 +423,9 @@ function findOriginalKeys(dependencies, node) {
         if (!keys.some((k) => k.startsWith(`${node.data.packageName}@`))) {
             continue;
         }
-        // standard package
-        if (snapshot.version === node.data.version) {
-            return [keys, snapshot];
-        }
-        // berry alias package
-        if (snapshot.resolution &&
-            `npm:${snapshot.resolution}` === node.data.version) {
-            return [keys, snapshot];
-        }
-        // classic alias
-        if (node.data.version.startsWith('npm:') &&
-            keys.some((k) => k === `${node.data.packageName}@${node.data.version}`)) {
+        if (isStandardPackage(snapshot, node.data.version) ||
+            isBerryAlias(snapshot, node.data.version) ||
+            isClassicAlias(node, keys)) {
             return [keys, snapshot];
         }
         // tarball package
@@ -400,16 +435,27 @@ function findOriginalKeys(dependencies, node) {
         }
     }
 }
-function findPatchedKeys(dependencies, node) {
+function findPatchedKeys(dependencies, node, resolutionVersion) {
     for (const keyExpr of Object.keys(dependencies)) {
         const snapshot = dependencies[keyExpr];
         const keys = keyExpr.split(', ');
         if (!keys[0].startsWith(`${node.data.packageName}@patch:`)) {
             continue;
         }
-        // local patches are currently not supported
-        if (keys[0].includes('.yarn/patches')) {
-            continue;
+        if (keyExpr.includes('.yarn/patches')) {
+            if (!resolutionVersion) {
+                continue;
+            }
+            const key = `${node.data.packageName}@${resolutionVersion}`;
+            // local patches can have different location from than the root lock file
+            // use the one from local package.json as the source of truth as long as the rest of the patch matches
+            // this obviously doesn't cover the case of patch over a patch, but that's a super rare case and one can argue one can just join those two patches
+            if (key.split('::locator')[0] !== keyExpr.split('::locator')[0]) {
+                continue;
+            }
+            else {
+                return [[key], { ...snapshot, resolution: key }];
+            }
         }
         if (snapshot.version === node.data.version) {
             return [keys, snapshot];

package/src/plugins/js/project-graph/affected/lock-file-changes.js

@@ -19,6 +19,7 @@ const getTouchedProjectsFromLockFile = (fileChanges, projectGraphNodes) => {
         'pnpm-lock.yaml',
         'pnpm-lock.yml',
         'bun.lockb',
+        'bun.lock',
     ];
     if (fileChanges.some((f) => lockFiles.includes(f.file))) {
         return Object.values(projectGraphNodes).map((p) => p.name);

package/src/plugins/js/project-graph/build-dependencies/explicit-project-dependencies.js

@@ -38,7 +38,7 @@ function buildExplicitTypeScriptDependencies(ctx, targetProjectLocator) {
     if (isVuePluginInstalled()) {
         moduleExtensions.push('.vue');
     }
-    for (const [project, fileData] of Object.entries(ctx.fileMap.projectFileMap)) {
+    for (const [project, fileData] of Object.entries(ctx.filesToProcess.projectFileMap)) {
         filesToProcess[project] ??= [];
         for (const { file } of fileData) {
             if (moduleExtensions.some((ext) => file.endsWith(ext))) {

package/src/plugins/js/project-graph/build-dependencies/target-project-locator.d.ts

@@ -5,6 +5,11 @@ import type { ProjectGraphExternalNode, ProjectGraphProjectNode } from '../../..
  * resolved external node name from the project graph.
  */
 type NpmResolutionCache = Map<string, string | null>;
+type PathPattern = {
+    pattern: string;
+    prefix: string;
+    suffix: string;
+};
 export declare function isBuiltinModuleImport(importExpr: string): boolean;
 export declare class TargetProjectLocator {
     private readonly nodes;
@@ -14,6 +19,7 @@ export declare class TargetProjectLocator {
     private npmProjects;
     private tsConfig;
     private paths;
+    private parsedPathPatterns;
     private typescriptResolutionCache;
     private packagesMetadata;
     constructor(nodes: Record<string, ProjectGraphProjectNode>, externalNodes?: Record<string, ProjectGraphExternalNode>, npmResolutionCache?: NpmResolutionCache);
@@ -36,11 +42,14 @@ export declare class TargetProjectLocator {
     /**
      * Return file paths matching the import relative to the repo root
      * @param normalizedImportExpr
-     * @returns
+     * @deprecated Use `findMatchingPaths` instead. It will be removed in Nx v22.
      */
     findPaths(normalizedImportExpr: string): string[] | undefined;
+    findMatchingPaths(importExpr: string): [pattern: string | PathPattern, paths: string[]] | undefined;
     findImportInWorkspaceProjects(importPath: string): string | null;
     findDependencyInWorkspaceProjects(dep: string): string | null;
+    private isPatternMatch;
+    private parsePaths;
     private resolveImportWithTypescript;
     private resolveImportWithRequire;
     private findProjectOfResolvedModule;

package/src/plugins/js/project-graph/build-dependencies/target-project-locator.js

@@ -49,6 +49,9 @@ class TargetProjectLocator {
             }
             return acc;
         }, {});
+        if (this.tsConfig.config?.compilerOptions?.paths) {
+            this.parsePaths(this.tsConfig.config.compilerOptions.paths);
+        }
     }
     /**
      * Resolve any workspace or external project that matches the given import expression,
@@ -63,14 +66,15 @@ class TargetProjectLocator {
             return this.findProjectOfResolvedModule(resolvedModule);
         }
         // find project using tsconfig paths
-        const results = this.findPaths(importExpr);
+        const results = this.findMatchingPaths(importExpr);
         if (results) {
             const [path, paths] = results;
+            const matchedStar = typeof path === 'string'
+                ? undefined
+                : importExpr.substring(path.prefix.length, importExpr.length - path.suffix.length);
             for (let p of paths) {
-                const r = p.endsWith('/*')
-                    ? (0, node_path_1.join)((0, node_path_1.dirname)(p), (0, node_path_1.relative)(path.replace(/\*$/, ''), importExpr))
-                    : p;
-                const maybeResolvedProject = this.findProjectOfResolvedModule(r);
+                const path = matchedStar ? p.replace('*', matchedStar) : p;
+                const maybeResolvedProject = this.findProjectOfResolvedModule(path);
                 if (maybeResolvedProject) {
                     return maybeResolvedProject;
                 }
@@ -172,7 +176,7 @@ class TargetProjectLocator {
     /**
      * Return file paths matching the import relative to the repo root
      * @param normalizedImportExpr
-     * @returns
+     * @deprecated Use `findMatchingPaths` instead. It will be removed in Nx v22.
      */
     findPaths(normalizedImportExpr) {
         if (!this.paths) {
@@ -189,6 +193,29 @@ class TargetProjectLocator {
         }
         return undefined;
     }
+    findMatchingPaths(importExpr) {
+        if (!this.parsedPathPatterns) {
+            return undefined;
+        }
+        const { matchableStrings, patterns } = this.parsedPathPatterns;
+        if (matchableStrings.has(importExpr)) {
+            return [importExpr, this.paths[importExpr]];
+        }
+        // https://github.com/microsoft/TypeScript/blob/29e6d6689dfb422e4f1395546c1917d07e1f664d/src/compiler/core.ts#L2410
+        let matchedValue;
+        let longestMatchPrefixLength = -1;
+        for (let i = 0; i < patterns.length; i++) {
+            const pattern = patterns[i];
+            if (pattern.prefix.length > longestMatchPrefixLength &&
+                this.isPatternMatch(pattern, importExpr)) {
+                longestMatchPrefixLength = pattern.prefix.length;
+                matchedValue = pattern;
+            }
+        }
+        return matchedValue
+            ? [matchedValue, this.paths[matchedValue.pattern]]
+            : undefined;
+    }
     findImportInWorkspaceProjects(importPath) {
         this.packagesMetadata ??= (0, packages_1.getWorkspacePackagesMetadata)(this.nodes);
         if (this.packagesMetadata.entryPointsToProjectMap[importPath]) {
@@ -201,6 +228,32 @@ class TargetProjectLocator {
         this.packagesMetadata ??= (0, packages_1.getWorkspacePackagesMetadata)(this.nodes);
         return this.packagesMetadata.packageToProjectMap[dep]?.name;
     }
+    isPatternMatch({ prefix, suffix }, candidate) {
+        return (candidate.length >= prefix.length + suffix.length &&
+            candidate.startsWith(prefix) &&
+            candidate.endsWith(suffix));
+    }
+    parsePaths(paths) {
+        this.parsedPathPatterns = {
+            matchableStrings: new Set(),
+            patterns: [],
+        };
+        for (const key of Object.keys(paths)) {
+            const parts = key.split('*');
+            if (parts.length > 2) {
+                continue;
+            }
+            if (parts.length === 1) {
+                this.parsedPathPatterns.matchableStrings.add(key);
+                continue;
+            }
+            this.parsedPathPatterns.patterns.push({
+                pattern: key,
+                prefix: parts[0],
+                suffix: parts[1],
+            });
+        }
+    }
     resolveImportWithTypescript(normalizedImportExpr, filePath) {
         let resolvedModule;
         if (this.typescriptResolutionCache.has(normalizedImportExpr)) {

package/src/plugins/js/utils/packages.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getWorkspacePackagesMetadata = getWorkspacePackagesMetadata;
 exports.matchImportToWildcardEntryPointsToProjectMap = matchImportToWildcardEntryPointsToProjectMap;
-const minimatch_1 = require("minimatch");
 const posix_1 = require("node:path/posix");
 function getWorkspacePackagesMetadata(projects) {
     const entryPointsToProjectMap = {};
@@ -63,10 +62,30 @@ function getWorkspacePackagesMetadata(projects) {
         packageToProjectMap,
     };
 }
+// adapted from PACKAGE_IMPORTS_EXPORTS_RESOLVE at
+// https://nodejs.org/docs/latest-v22.x/api/esm.html#resolution-algorithm-specification
 function matchImportToWildcardEntryPointsToProjectMap(wildcardEntryPointsToProjectMap, importPath) {
     if (!Object.keys(wildcardEntryPointsToProjectMap).length) {
         return null;
     }
-    const matchingPair = Object.entries(wildcardEntryPointsToProjectMap).find(([key]) => (0, minimatch_1.minimatch)(importPath, key));
-    return matchingPair?.[1];
+    const entryPoint = Object.keys(wildcardEntryPointsToProjectMap).find((key) => {
+        const segments = key.split('*');
+        if (segments.length > 2) {
+            return false;
+        }
+        const patternBase = segments[0];
+        if (patternBase === importPath) {
+            return false;
+        }
+        if (!importPath.startsWith(patternBase)) {
+            return false;
+        }
+        const patternTrailer = segments[1];
+        if (patternTrailer?.length > 0 &&
+            (!importPath.endsWith(patternTrailer) || importPath.length < key.length)) {
+            return false;
+        }
+        return true;
+    });
+    return entryPoint ? wildcardEntryPointsToProjectMap[entryPoint] : null;
 }

package/src/plugins/js/utils/register.js

@@ -161,6 +161,7 @@ function getTranspiler(compilerOptions, tsConfigRaw) {
     // use NodeJs module resolution until support for TS 4.x is dropped and then
     // we can switch to Node10
     compilerOptions.moduleResolution = ts.ModuleResolutionKind.NodeJs;
+    compilerOptions.customConditions = null;
     compilerOptions.target = ts.ScriptTarget.ES2021;
     compilerOptions.inlineSourceMap = true;
     compilerOptions.skipLibCheck = true;

package/src/plugins/js/utils/typescript.js

@@ -23,11 +23,11 @@ function readTsConfigOptions(tsConfigPath) {
         tsModule = require('typescript');
     }
     const readResult = tsModule.readConfigFile(tsConfigPath, tsModule.sys.readFile);
-    // we don't need to scan the files, we only care about options
+    // We only care about options, so we don't need to scan source files, and thus
+    // `readDirectory` is stubbed for performance.
     const host = {
+        ...tsModule.sys,
         readDirectory: () => [],
-        readFile: () => '',
-        fileExists: tsModule.sys.fileExists,
     };
     return tsModule.parseJsonConfigFileContent(readResult.config, host, (0, path_1.dirname)(tsConfigPath)).options;
 }

package/src/plugins/package-json/create-nodes.d.ts

@@ -1,5 +1,5 @@
 import { NxJsonConfiguration } from '../../config/nx-json';
-import { ProjectConfiguration } from '../../config/workspace-json-project-json';
+import type { ProjectConfiguration } from '../../config/workspace-json-project-json';
 import { PackageJson } from '../../utils/package-json';
 import { CreateNodesV2 } from '../../project-graph/plugins';
 import { PackageJsonConfigurationCache } from '../../../plugins/package-json';

package/src/plugins/package-json/create-nodes.js

@@ -86,6 +86,9 @@ function createNodeFromPackageJson(pkgJsonPath, workspaceRoot, cache, isInPackag
         ...json,
         root: projectRoot,
         isInPackageManagerWorkspaces,
+        // change this to bust the cache when making changes that result in different
+        // results for the same hash
+        bust: 1,
     });
     const cached = cache[hash];
     if (cached) {
@@ -126,10 +129,9 @@ function buildProjectConfigurationFromPackageJson(packageJson, workspaceRoot, pa
     let name = packageJson.name ?? (0, to_project_name_1.toProjectName)(normalizedPath);
     const projectConfiguration = {
         root: projectRoot,
-        sourceRoot: projectRoot,
         name,
         ...packageJson.nx,
-        targets: (0, package_json_1.readTargetsFromPackageJson)(packageJson, nxJson),
+        targets: (0, package_json_1.readTargetsFromPackageJson)(packageJson, nxJson, projectRoot, workspaceRoot),
         tags: (0, package_json_1.getTagsFromPackageJson)(packageJson),
         metadata: (0, package_json_1.getMetadataFromPackageJson)(packageJson, isInPackageManagerWorkspaces),
     };

package/src/project-graph/affected/locators/project-glob-changes.js

@@ -20,8 +20,8 @@ const getTouchedProjectsFromProjectGlobChanges = async (touchedFiles, projectGra
                 'package.json',
             ]);
         }
-        const plugins = await (0, get_plugins_1.getPlugins)();
-        return (0, globs_1.combineGlobPatterns)((0, retrieve_workspace_files_1.configurationGlobs)(plugins));
+        const plugins = (await (0, get_plugins_1.getPlugins)()).filter((p) => !!p.createNodes);
+        return (0, globs_1.combineGlobPatterns)((0, retrieve_workspace_files_1.getGlobPatternsOfPlugins)(plugins));
     })();
     const touchedProjects = new Set();
     for (const touchedFile of touchedFiles) {

package/src/project-graph/error-types.js

@@ -153,10 +153,37 @@ function isProjectWithNoNameError(e) {
 }
 class ProjectConfigurationsError extends Error {
     constructor(errors, partialProjectConfigurationsResult) {
-        super('Failed to create project configurations');
+        const messageFragments = ['Failed to create project configurations.'];
+        const mergeNodesErrors = [];
+        const unknownErrors = [];
+        for (const e of errors) {
+            if (
+            // Known error type, but unlikely to be caused by the user
+            isMergeNodesError(e)) {
+                mergeNodesErrors.push(e);
+            }
+            else if (
+            // Known errors that are self-explanatory
+            !isAggregateCreateNodesError(e) &&
+                !isProjectsWithNoNameError(e) &&
+                !isMultipleProjectsWithSameNameError(e)) {
+                unknownErrors.push(e);
+            }
+        }
+        if (mergeNodesErrors.length > 0) {
+            messageFragments.push(`This type of error most likely points to an issue within Nx. Please report it.`);
+        }
+        if (unknownErrors.length > 0) {
+            messageFragments.push(`If the error cause is not obvious from the below error messages, running "nx reset" may fix it. Please report the issue if you keep seeing it.`);
+        }
+        super(messageFragments.join(' '));
         this.errors = errors;
         this.partialProjectConfigurationsResult = partialProjectConfigurationsResult;
         this.name = this.constructor.name;
+        this.errors = errors;
+        this.stack = errors
+            .map((error) => indentString(formatErrorStackAndCause(error), 2))
+            .join('\n');
     }
 }
 exports.ProjectConfigurationsError = ProjectConfigurationsError;
@@ -216,7 +243,10 @@ class AggregateCreateNodesError extends Error {
 exports.AggregateCreateNodesError = AggregateCreateNodesError;
 function formatAggregateCreateNodesError(error, pluginName) {
     const errorBodyLines = [
-        `${error.errors.length > 1 ? `${error.errors.length} errors` : 'An error'} occurred while processing files for the ${pluginName} plugin.`,
+        `${error.errors.length > 1 ? `${error.errors.length} errors` : 'An error'} occurred while processing files for the ${pluginName} plugin${error.pluginIndex
+            ? ` (Defined at nx.json#plugins[${error.pluginIndex}])`
+            : ''}`,
+        `.`,
     ];
     const errorStackLines = [];
     const innerErrors = error.errors;

package/src/project-graph/file-utils.d.ts

@@ -1,5 +1,4 @@
-import { FileData } from '../config/project-graph';
-import { ProjectsConfigurations } from '../config/workspace-json-project-json';
+import type { FileData } from '../config/project-graph';
 import type { NxArgs } from '../utils/command-line-utils';
 export interface Change {
     type: string;
@@ -17,14 +16,6 @@ export declare function isWholeFileChange(change: Change): change is WholeFileCh
 export declare function isDeletedFileChange(change: Change): change is DeletedFileChange;
 export declare function calculateFileChanges(files: string[], allWorkspaceFiles: FileData[], nxArgs?: NxArgs, readFileAtRevision?: (f: string, r: void | string) => string, ignore?: ReturnType<typeof ignore>): FileChange[];
 export declare const TEN_MEGABYTES: number;
-/**
- * TODO(v21): Remove this function
- * @deprecated To get projects use {@link retrieveProjectConfigurations} instead. This will be removed in v21.
- */
-export declare function readWorkspaceConfig(opts: {
-    format: 'angularCli' | 'nx';
-    path?: string;
-}): ProjectsConfigurations;
 export declare function defaultFileRead(filePath: string): string | null;
 export declare function readPackageJson(root?: string): any;
 export { FileData };