feat: add pnpm doctor command to do checks for known common issues

.changeset/gentle-lobsters-sit.md

@@ -0,0 +1,6 @@
+---
+"@pnpm/plugin-commands-audit": minor
+"pnpm": minor
+---
+
+Add `pnpm doctor` command to do checks for known common issues

packages/plugin-commands-audit/package.json

@@ -34,9 +34,11 @@
     "@pnpm/plugin-commands-audit": "workspace:*",
     "@pnpm/test-fixtures": "workspace:*",
     "@types/ramda": "0.28.15",
+    "@types/sinon": "^10.0.13",
     "@types/zkochan__table": "npm:@types/table@6.0.0",
     "load-json-file": "^6.2.0",
     "nock": "13.2.9",
+    "sinon": "^14.0.1",
     "strip-ansi": "^6.0.1",
     "tempy": "^1.0.1"
   },
@@ -59,5 +61,8 @@
   "funding": "https://opencollective.com/pnpm",
   "exports": {
     ".": "./lib/index.js"
+  },
+  "peerDependencies": {
+    "@pnpm/logger": "^5.0.0"
   }
 }

packages/plugin-commands-audit/src/doctor.ts

@@ -0,0 +1,62 @@
+import renderHelp from 'render-help'
+import { docsUrl } from '@pnpm/cli-utils'
+import { logger } from '@pnpm/logger'
+
+export const rcOptionsTypes = cliOptionsTypes
+
+export function cliOptionsTypes () {
+  return {
+    config: Boolean,
+  }
+}
+
+export const shorthands = {
+  C: '--config',
+}
+
+export const commandNames = ['doctor']
+
+export function help () {
+  return renderHelp({
+    description: 'Checks for known common issues.',
+    descriptionLists: [
+      {
+        title: 'Options',
+        list: [
+          {
+            description: 'Check the global config',
+            name: '--config',
+            shortAlias: '-C',
+          },
+        ],
+      },
+    ],
+    url: docsUrl('doctor'),
+    usages: ['pnpm doctor [options]'],
+  })
+}
+
+export async function handler (
+  opts: {
+    config: boolean
+  }) {
+  if (opts.config) {
+    const paths = require.resolve.paths('npm')
+    try {
+      require.resolve('npm', { paths: paths?.slice(-1) })
+    } catch (e) {
+      // If error, means loading npm builtin config failed
+      if (
+        process.platform === 'darwin' &&
+        process.env.HOMEBREW_PREFIX &&
+        process.execPath.startsWith(process.env.HOMEBREW_PREFIX)
+      ) {
+        // Npm installed via brew may have prefix error, related: https://github.com/pnpm/pnpm/issues/5404
+        logger.warn({
+          message: 'Load npm builtin configs failed. If the prefix builtin config does not work, you can use "pnpm config ls" to show builtin configs. And then use "pnpm config --global set <key> <value>" to migrate configs from builtin to global.',
+          prefix: process.cwd(),
+        })
+      }
+    }
+  }
+}

packages/plugin-commands-audit/src/index.ts

@@ -1,3 +1,7 @@
 import * as audit from './audit'
+import * as doctor from './doctor'
 
-export { audit }
+export {
+  audit,
+  doctor,
+}

packages/plugin-commands-audit/test/doctor.ts

@@ -0,0 +1,35 @@
+import { doctor } from '@pnpm/plugin-commands-audit'
+import sinon from 'sinon'
+import { logger } from '@pnpm/logger'
+
+test('doctor --config', async () => {
+  const oldExecPath = process.execPath
+  const oldPlatform = process.platform
+  const oldEnv = process.env
+  const HOMEBREW_PREFIX = '.'
+
+  process.env = { ...oldEnv, HOMEBREW_PREFIX }
+  process.execPath = HOMEBREW_PREFIX
+  // platform is read only
+  Object.defineProperty(process, 'platform', {
+    value: 'darwin',
+  })
+
+  const reporter = sinon.spy(logger, 'warn')
+
+  // In the scope of jest, require.resolve.paths('npm') cannot reach global npm path by default
+  await doctor.handler({
+    config: true,
+  })
+
+  expect(reporter.calledWithMatch({
+    message: 'Load npm builtin configs failed. If the prefix builtin config does not work, you can use "pnpm config ls" to show builtin configs. And then use "pnpm config --global set <key> <value>" to migrate configs from builtin to global.',
+    prefix: process.cwd(),
+  })).toBeTruthy()
+
+  process.env = oldEnv
+  process.execPath = oldExecPath
+  Object.defineProperty(process, 'platform', {
+    value: oldPlatform,
+  })
+})

packages/pnpm/src/cmd/index.ts

@@ -1,6 +1,9 @@
 import { CompletionFunc } from '@pnpm/command'
 import { types as allTypes } from '@pnpm/config'
-import { audit } from '@pnpm/plugin-commands-audit'
+import {
+  audit,
+  doctor,
+} from '@pnpm/plugin-commands-audit'
 import { env } from '@pnpm/plugin-commands-env'
 import { deploy } from '@pnpm/plugin-commands-deploy'
 import { add, fetch, install, link, prune, remove, unlink, update, importCommand } from '@pnpm/plugin-commands-installation'
@@ -100,6 +103,7 @@ const commands: CommandDefinition[] = [
   create,
   deploy,
   dlx,
+  doctor,
   env,
   exec,
   fetch,