feat(core): add multiple Nx version detection to nx report (#33599)

FrozenPandaz · FrozenPandaz · commit b9a7703f28b2 · 2025-11-25T18:45:03.000-05:00
## Current Behavior When multiple versions of the `nx` package are installed in a workspace (e.g., due to a third-party package incorrectly depending on nx), users have no visibility into this issue through `nx report`. ## Expected Behavior The `nx report` command now detects when other packages depend on a different version of nx than the workspace version and reports this clearly: ⚠️ Multiple Nx versions detected Your workspace uses nx@20.0.0, but other packages depend on a different version: - some-package → @scope/tool → nx@19.0.0 These packages should not have nx as a dependency. Please report this issue to the package maintainers. Run pnpm why nx@19.0.0 for more details. This helps users identify and report problematic packages that bundle their own version of nx. ## Related Issue(s) N/A - This is a proactive improvement to help users diagnose workspace issues.
diff --git a/packages/nx/src/command-line/report/report.ts b/packages/nx/src/command-line/report/report.ts
@@ -3,6 +3,7 @@ import { output } from '../../utils/output';
 import { join } from 'path';
 import {
   detectPackageManager,
+  getPackageManagerCommand,
   getPackageManagerVersion,
   PackageManager,
 } from '../../utils/package-manager';
@@ -23,6 +24,8 @@ import { getNxRequirePaths } from '../../utils/installation-directory';
 import { NxJsonConfiguration, readNxJson } from '../../config/nx-json';
 import { ProjectGraph } from '../../config/project-graph';
 import { ProjectGraphError } from '../../project-graph/error-types';
+import { reverse } from '../../project-graph/operators';
+import { nxVersion } from '../../utils/versions';
 import {
   getNxKeyInformation,
   NxKeyNotInstalledError,
@@ -79,6 +82,7 @@ export async function reportHandler() {
     registeredPlugins,
     packageVersionsWeCareAbout,
     outOfSyncPackageGroup,
+    mismatchedNxVersions,
     projectGraphError,
     nativeTarget,
     cache,
@@ -221,6 +225,32 @@ export async function reportHandler() {
     );
   }
 
+  if (mismatchedNxVersions && mismatchedNxVersions.length > 0) {
+    bodyLines.push(LINE_SEPARATOR);
+    bodyLines.push(chalk.yellow('⚠️ Multiple Nx versions detected'));
+    bodyLines.push('');
+    bodyLines.push(
+      `Your workspace uses nx@${nxVersion}, but other packages depend on a different version:`
+    );
+    for (const { version, chain } of mismatchedNxVersions) {
+      if (chain.length === 0) {
+        bodyLines.push(`  - ${chalk.bold(`nx@${version}`)}`);
+      } else {
+        bodyLines.push(
+          `  - ${chain.reverse().join(' → ')} → ${chalk.bold(`nx@${version}`)}`
+        );
+      }
+    }
+    bodyLines.push('');
+    bodyLines.push(
+      'These packages should not have nx as a dependency. Please report this issue to the package maintainers.'
+    );
+    const whyCommand = getPackageManagerCommand(pm).why;
+    for (const { version } of mismatchedNxVersions) {
+      bodyLines.push(`Run \`${whyCommand} nx@${version}\` for more details.`);
+    }
+  }
+
   if (projectGraphError) {
     bodyLines.push(LINE_SEPARATOR);
     bodyLines.push('⚠️ Unable to construct project graph.');
@@ -255,6 +285,10 @@ export interface ReportData {
     }[];
     migrateTarget: string;
   };
+  mismatchedNxVersions?: Array<{
+    version: string;
+    chain: string[];
+  }>;
   projectGraphError?: Error | null;
   nativeTarget: string | null;
   cache: {
@@ -263,6 +297,71 @@ export interface ReportData {
   } | null;
 }
 
+function findDependencyChain(
+  graph: ProjectGraph,
+  targetNode: string
+): string[] {
+  const reversedGraph = reverse(graph);
+
+  // BFS to find shortest path to root dependency
+  const queue: { node: string; path: string[] }[] = [
+    { node: targetNode, path: [] },
+  ];
+  const visited = new Set<string>();
+
+  while (queue.length > 0) {
+    const { node, path } = queue.shift()!;
+
+    if (visited.has(node)) continue;
+    visited.add(node);
+
+    const deps = reversedGraph.dependencies[node] || [];
+
+    // Check for unvisited dependents
+    const unvisitedDeps = deps.filter((dep) => !visited.has(dep.target));
+
+    // No unvisited dependents - this is our shortest path
+    if (unvisitedDeps.length === 0) {
+      return path;
+    }
+
+    for (const dep of unvisitedDeps) {
+      const depName =
+        graph.externalNodes?.[dep.target]?.data?.packageName ?? dep.target;
+      queue.push({
+        node: dep.target,
+        path: [...path, depName],
+      });
+    }
+  }
+
+  return [];
+}
+
+function findMismatchedNxVersions(
+  graph: ProjectGraph
+): Array<{ version: string; chain: string[] }> {
+  if (!graph || !graph.externalNodes) {
+    return [];
+  }
+
+  const result: Array<{ version: string; chain: string[] }> = [];
+
+  // Find all nx package versions that don't match the workspace version
+  for (const nodeName of Object.keys(graph.externalNodes)) {
+    const node = graph.externalNodes[nodeName];
+    if (node.data?.packageName === 'nx') {
+      const version = node.data.version || 'unknown';
+      if (version !== nxVersion) {
+        const chain = findDependencyChain(graph, nodeName);
+        result.push({ version, chain });
+      }
+    }
+  }
+
+  return result;
+}
+
 export async function getReportData(): Promise<ReportData> {
   const pm = detectPackageManager();
   const pmVersion = getPackageManagerVersion(pm);
@@ -289,6 +388,8 @@ export async function getReportData(): Promise<ReportData> {
 
   const outOfSyncPackageGroup = findMisalignedPackagesForPackage(nxPackageJson);
 
+  const mismatchedNxVersions = findMismatchedNxVersions(graph);
+
   const native = isNativeAvailable();
 
   let nxKey = null;
@@ -319,6 +420,7 @@ export async function getReportData(): Promise<ReportData> {
     registeredPlugins,
     packageVersionsWeCareAbout,
     outOfSyncPackageGroup,
+    mismatchedNxVersions,
     projectGraphError,
     nativeTarget: native ? native.getBinaryTarget() : null,
     cache,
diff --git a/packages/nx/src/utils/package-manager.ts b/packages/nx/src/utils/package-manager.ts
@@ -42,6 +42,7 @@ export interface PackageManagerCommands {
   exec: string;
   dlx: string;
   list: string;
+  why: string;
   run: (script: string, args?: string) => string;
   // Make this required once bun adds programatically support for reading config https://github.com/oven-sh/bun/issues/7140
   getRegistryUrl?: string;
@@ -148,6 +149,7 @@ export function getPackageManagerCommand(
         run: (script: string, args?: string) =>
           `yarn ${script}${args ? ` ${args}` : ''}`,
         list: useBerry ? 'yarn info --name-only' : 'yarn list',
+        why: 'yarn why',
         getRegistryUrl: useBerry
           ? 'yarn config get npmRegistryServer'
           : 'yarn config get registry',
@@ -195,6 +197,7 @@ export function getPackageManagerCommand(
               : ''
           }`,
         list: 'pnpm ls --depth 100',
+        why: 'pnpm why',
         getRegistryUrl: 'pnpm config get registry',
         publish: (packageRoot, registry, registryConfigKey, tag) =>
           `pnpm publish "${packageRoot}" --json --"${
@@ -216,6 +219,7 @@ export function getPackageManagerCommand(
         run: (script: string, args?: string) =>
           `npm run ${script}${args ? ' -- ' + args : ''}`,
         list: 'npm ls',
+        why: 'npm explain',
         getRegistryUrl: 'npm config get registry',
         publish: (packageRoot, registry, registryConfigKey, tag) =>
           `npm publish "${packageRoot}" --json --"${registryConfigKey}=${registry}" --tag=${tag}`,
@@ -235,6 +239,7 @@ export function getPackageManagerCommand(
         dlx: 'bunx',
         run: (script: string, args: string) => `bun run ${script} -- ${args}`,
         list: 'bun pm ls',
+        why: 'bun why',
         // Unlike npm, bun publish does not support a custom registryConfigKey option
         publish: (packageRoot, registry, registryConfigKey, tag) =>
           `bun publish --cwd="${packageRoot}" --json --registry="${registry}" --tag=${tag}`,
