feat(@angular/cli): provide detailed peer dependency conflict errors in ng add

This commit enhances the `ng add` command's version resolution to provide more informative feedback to the user, especially when peer dependency conflicts occur. Key improvements include: - When a compatible version cannot be found, the command now lists the specific peer dependency conflicts that caused recent versions to be rejected. By default, up to 5 conflicts are shown. - The peer dependency check now collects and reports all conflicts for a given package version, not just the first one it finds. - In verbose mode (`--verbose`), all detected peer dependency conflicts will be displayed.

Author: clydin

packages/angular/cli/src/commands/add/cli.ts

@@ -49,7 +49,7 @@ interface AddCommandTaskContext {
  savePackage?: NgAddSaveDependency;
  collectionName?: string;
  executeSchematic: AddCommandModule['executeSchematic'];
- hasMismatchedPeer: AddCommandModule['hasMismatchedPeer'];
+ getPeerDependencyConflicts: AddCommandModule['getPeerDependencyConflicts'];
 }
 
 type AddCommandTaskWrapper = ListrTaskWrapper<
@@ -70,6 +70,8 @@ const packageVersionExclusions: Record<string, string | Range> = {
  '@angular/material': '7.x',
 };
 
+const DEFAULT_CONFLICT_DISPLAY_LIMIT = 5;
+
 export default class AddCommandModule
  extends SchematicsCommandModule
  implements CommandModuleImplementation<AddCommandArgs>
@@ -158,7 +160,7 @@ export default class AddCommandModule
  const taskContext: AddCommandTaskContext = {
  packageIdentifier,
  executeSchematic: this.executeSchematic.bind(this),
- hasMismatchedPeer: this.hasMismatchedPeer.bind(this),
+ getPeerDependencyConflicts: this.getPeerDependencyConflicts.bind(this),
  };
 
  const tasks = new Listr<AddCommandTaskContext>(
@@ -248,69 +250,83 @@ export default class AddCommandModule
  throw new CommandError(`Unable to load package information from registry: ${e.message}`);
  }
 
+ const rejectionReasons: string[] = [];
+
  // Start with the version tagged as `latest` if it exists
  const latestManifest = packageMetadata.tags['latest'];
  if (latestManifest) {
- context.packageIdentifier = npa.resolve(latestManifest.name, latestManifest.version);
+ const latestConflicts = await this.getPeerDependencyConflicts(latestManifest);
+ if (latestConflicts) {
+ // 'latest' is invalid so search for most recent matching package
+ rejectionReasons.push(...latestConflicts);
+ } else {
+ context.packageIdentifier = npa.resolve(latestManifest.name, latestManifest.version);
+ task.output = `Found compatible package version: ${color.blue(latestManifest.version)}.`;
+
+ return;
+ }
  }
 
- // Adjust the version based on name and peer dependencies
- if (
- latestManifest?.peerDependencies &&
- Object.keys(latestManifest.peerDependencies).length === 0
- ) {
- task.output = `Found compatible package version: ${color.blue(latestManifest.version)}.`;
- } else if (!latestManifest || (await context.hasMismatchedPeer(latestManifest))) {
- // 'latest' is invalid so search for most recent matching package
-
- // Allow prelease versions if the CLI itself is a prerelease
- const allowPrereleases = prerelease(VERSION.full);
-
- const versionExclusions = packageVersionExclusions[packageMetadata.name];
- const versionManifests = Object.values(packageMetadata.versions).filter(
- (value: PackageManifest) => {
- // Prerelease versions are not stable and should not be considered by default
- if (!allowPrereleases && prerelease(value.version)) {
- return false;
- }
- // Deprecated versions should not be used or considered
- if (value.deprecated) {
- return false;
- }
- // Excluded package versions should not be considered
- if (
- versionExclusions &&
- satisfies(value.version, versionExclusions, { includePrerelease: true })
- ) {
- return false;
- }
+ // Allow prelease versions if the CLI itself is a prerelease
+ const allowPrereleases = prerelease(VERSION.full);
 
- return true;
- },
- );
+ const versionExclusions = packageVersionExclusions[packageMetadata.name];
+ const versionManifests = Object.values(packageMetadata.versions).filter(
+ (value: PackageManifest) => {
+ // Already checked the 'latest' version
+ if (latestManifest.version === value.version) {
+ return false;
+ }
+ // Prerelease versions are not stable and should not be considered by default
+ if (!allowPrereleases && prerelease(value.version)) {
+ return false;
+ }
+ // Deprecated versions should not be used or considered
+ if (value.deprecated) {
+ return false;
+ }
+ // Excluded package versions should not be considered
+ if (
+ versionExclusions &&
+ satisfies(value.version, versionExclusions, { includePrerelease: true })
+ ) {
+ return false;
+ }
 
- // Sort in reverse SemVer order so that the newest compatible version is chosen
- versionManifests.sort((a, b) => compare(b.version, a.version, true));
+ return true;
+ },
+ );
 
- let found = false;
- for (const versionManifest of versionManifests) {
- const mismatch = await context.hasMismatchedPeer(versionManifest);
- if (mismatch) {
- continue;
- }
+ // Sort in reverse SemVer order so that the newest compatible version is chosen
+ versionManifests.sort((a, b) => compare(b.version, a.version, true));
 
- context.packageIdentifier = npa.resolve(versionManifest.name, versionManifest.version);
- found = true;
- break;
+ let found = false;
+ for (const versionManifest of versionManifests) {
+ const conflicts = await this.getPeerDependencyConflicts(versionManifest);
+ if (conflicts) {
+ if (options.verbose || rejectionReasons.length < DEFAULT_CONFLICT_DISPLAY_LIMIT) {
+ rejectionReasons.push(...conflicts);
+ }
+ continue;
  }
 
- if (!found) {
- task.output = "Unable to find compatible package. Using 'latest' tag.";
- } else {
- task.output = `Found compatible package version: ${color.blue(
- context.packageIdentifier.toString(),
- )}.`;
+ context.packageIdentifier = npa.resolve(versionManifest.name, versionManifest.version);
+ found = true;
+ break;
+ }
+
+ if (!found) {
+ let message = `Unable to find compatible package. Using 'latest' tag.`;
+ if (rejectionReasons.length > 0) {
+ message +=
+ '\nThis is often because of incompatible peer dependencies.\n' +
+ 'These versions were rejected due to the following conflicts:\n' +
+ rejectionReasons
+ .slice(0, options.verbose ? undefined : DEFAULT_CONFLICT_DISPLAY_LIMIT)
+ .map((r) => ` - ${r}`)
+ .join('\n');
  }
+ task.output = message;
  } else {
  task.output = `Found compatible package version: ${color.blue(
  context.packageIdentifier.toString(),
@@ -343,7 +359,7 @@ export default class AddCommandModule
  context.savePackage = manifest['ng-add']?.save;
  context.collectionName = manifest.name;
 
- if (await context.hasMismatchedPeer(manifest)) {
+ if (await this.getPeerDependencyConflicts(manifest)) {
  task.output = color.yellow(
  figures.warning +
  ' Package has unmet peer dependencies. Adding the package may not succeed.',
@@ -563,7 +579,8 @@ export default class AddCommandModule
  return null;
  }
 
- private async hasMismatchedPeer(manifest: PackageManifest): Promise<boolean> {
+ private async getPeerDependencyConflicts(manifest: PackageManifest): Promise<string[] | false> {
+ const conflicts: string[] = [];
  for (const peer in manifest.peerDependencies) {
  let peerIdentifier;
  try {
@@ -586,7 +603,10 @@ export default class AddCommandModule
  !intersects(version, peerIdentifier.rawSpec, options) &&
  !satisfies(version, peerIdentifier.rawSpec, options)
  ) {
- return true;
+ conflicts.push(
+ `Package "${manifest.name}@${manifest.version}" has an incompatible peer dependency to "` +
+ `${peer}@${peerIdentifier.rawSpec}" (requires "${version}" in project).`,
+ );
  }
  } catch {
  // Not found or invalid so ignore
@@ -598,6 +618,6 @@ export default class AddCommandModule
  }
  }
 
- return false;
+ return conflicts.length > 0 && conflicts;
  }
 }