feat(nuxi): add --verbose and --json flags to doctor

Author: onmax

packages/nuxi/src/commands/doctor.ts

@@ -13,33 +13,50 @@ import { isBun, isDeno } from 'std-env'
 import { loadKit, tryResolveNuxt } from '../utils/kit'
 import { cwdArgs, legacyRootDirArgs, logLevelArgs } from './_shared'
 
-// Types for the hook-based architecture (will move to @nuxt/schema)
 interface DoctorCheck {
+  // Required
   name: string
   status: 'success' | 'warning' | 'error'
   message: string
-  source?: string // module name, e.g. "@nuxt/a11y"
-  details?: string[] // list of issues/details to display
+
+  // Optional - identity/origin
+  id?: string // programmatic code: "MISSING_PEER_DEP"
+  source?: string // module name: "@nuxt/ui"
+
+  // Optional - verbose fields
+  details?: string | string[]
+  suggestion?: string
+  url?: string
+
+  // Optional - programmatic
+  data?: Record<string, unknown>
 }
 
 interface DoctorCheckContext {
   addCheck: (check: DoctorCheck) => void
   nuxt: Nuxt
 }
 
-// Augment NuxtHooks for the doctor:check hook (will be moved to @nuxt/schema)
 declare module '@nuxt/schema' {
   interface NuxtHooks {
     'doctor:check': (ctx: DoctorCheckContext) => void | Promise<void>
   }
 }
 
+const plural = (n: number) => n === 1 ? '' : 's'
+
 async function resolveNuxtVersion(cwd: string): Promise<string | undefined> {
   const nuxtPath = tryResolveNuxt(cwd)
   for (const pkg of ['nuxt', 'nuxt-nightly', 'nuxt-edge', 'nuxt3']) {
-    const pkgJson = await readPackageJSON(pkg, { url: nuxtPath || cwd }).catch(() => null)
-    if (pkgJson?.version) {
-      return pkgJson.version
+    try {
+      const pkgJson = await readPackageJSON(pkg, { url: nuxtPath || cwd })
+      if (pkgJson?.version)
+        return pkgJson.version
+    }
+    catch (err: any) {
+      // Ignore "not found" errors, log unexpected ones
+      if (err?.code !== 'ERR_MODULE_NOT_FOUND' && err?.code !== 'ENOENT' && !err?.message?.includes('Cannot find'))
+        log.warn(`Failed to read ${pkg} version: ${err?.message || err}`)
     }
   }
 }
@@ -53,11 +70,20 @@ export default defineCommand({
     ...cwdArgs,
     ...legacyRootDirArgs,
     ...logLevelArgs,
+    verbose: {
+      type: 'boolean',
+      description: 'Show details, suggestions, and URLs',
+    },
+    json: {
+      type: 'boolean',
+      description: 'Output results as JSON',
+    },
   },
   async run(ctx) {
     const cwd = resolve(ctx.args.cwd || ctx.args.rootDir)
 
-    intro(colors.cyan('Running diagnostics...'))
+    if (!ctx.args.json)
+      intro(colors.cyan('Running diagnostics...'))
 
     const { loadNuxt } = await loadKit(cwd)
 
@@ -72,10 +98,15 @@ export default defineCommand({
       })
     }
     catch (err) {
-      log.error(colors.red(`Failed to load Nuxt: ${err instanceof Error ? err.message : String(err)}`))
-      outro(colors.red('Diagnostics failed'))
-      process.exit(1)
-      return // unreachable but needed for type narrowing in tests
+      if (ctx.args.json) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify([{ name: 'Nuxt', status: 'error', message: `Failed to load Nuxt: ${err instanceof Error ? err.message : String(err)}` }]))
+      }
+      else {
+        log.error(colors.red(`Failed to load Nuxt: ${err instanceof Error ? err.message : String(err)}`))
+        outro(colors.red('Diagnostics failed'))
+      }
+      return process.exit(1)
     }
 
     const checks: DoctorCheck[] = []
@@ -91,7 +122,7 @@ export default defineCommand({
       })
 
       // 3. Display results
-      displayResults(checks)
+      displayResults(checks, { verbose: ctx.args.verbose, json: ctx.args.json })
     }
     finally {
       await nuxt.close()
@@ -100,28 +131,33 @@ export default defineCommand({
     const hasErrors = checks.some(c => c.status === 'error')
     const hasWarnings = checks.some(c => c.status === 'warning')
 
-    if (hasErrors) {
-      outro(colors.red('Diagnostics complete with errors'))
-      process.exit(1)
-    }
-    else if (hasWarnings) {
-      outro(colors.yellow('Diagnostics complete with warnings'))
-    }
-    else {
-      outro(colors.green('All checks passed!'))
+    if (!ctx.args.json) {
+      if (hasErrors)
+        outro(colors.red('Diagnostics complete with errors'))
+      else if (hasWarnings)
+        outro(colors.yellow('Diagnostics complete with warnings'))
+      else
+        outro(colors.green('All checks passed!'))
     }
+
+    if (hasErrors)
+      process.exit(1)
   },
 })
 
 async function runCoreChecks(checks: DoctorCheck[], nuxt: Nuxt, cwd: string): Promise<void> {
-  // Version check
-  await checkVersions(checks, cwd)
-
-  // Config validation
-  checkConfig(checks, nuxt)
+  const runCheck = async (name: string, fn: () => void | Promise<void>) => {
+    try {
+      await fn()
+    }
+    catch (err) {
+      checks.push({ name, status: 'error', message: `Check failed: ${err instanceof Error ? err.message : String(err)}` })
+    }
+  }
 
-  // Module compatibility
-  await checkModuleCompat(checks, nuxt, cwd)
+  await runCheck('Versions', () => checkVersions(checks, cwd))
+  await runCheck('Config', () => checkConfig(checks, nuxt))
+  await runCheck('Modules', () => checkModuleCompat(checks, nuxt, cwd))
 }
 
 async function checkVersions(checks: DoctorCheck[], cwd: string): Promise<void> {
@@ -137,14 +173,14 @@ async function checkVersions(checks: DoctorCheck[], cwd: string): Promise<void>
 
   // Check Node.js version (if not Bun/Deno)
   if (!isBun && !isDeno) {
-    const nodeVersion = process.version
-    const major = Number.parseInt(nodeVersion.slice(1).split('.')[0] || '0', 10)
-
-    if (major < 18) {
+    if (!semverSatisfies(process.versions.node, '>= 18.0.0')) {
       checks.push({
+        id: 'UNSUPPORTED_NODE',
         name: 'Versions',
         status: 'error',
         message: `${runtime}, Nuxt ${nuxtVersion} - Node.js 18+ required`,
+        suggestion: 'Upgrade Node.js to v18 or later',
+        url: 'https://nuxt.com/docs/getting-started/installation#prerequisites',
       })
       return
     }
@@ -181,10 +217,13 @@ function checkConfig(checks: DoctorCheck[], nuxt: Nuxt): void {
 
   if (issues.length > 0) {
     checks.push({
+      id: 'CONFIG_ISSUES',
       name: 'Config',
       status: 'warning',
-      message: `${issues.length} issue${issues.length > 1 ? 's' : ''} found`,
+      message: `${issues.length} issue${plural(issues.length)} found`,
       details: issues,
+      suggestion: 'Review nuxt.config.ts and fix the issues above',
+      url: 'https://nuxt.com/docs/getting-started/configuration',
     })
   }
   else {
@@ -224,17 +263,20 @@ async function checkModuleCompat(checks: DoctorCheck[], nuxt: Nuxt, cwd: string)
 
   if (issues.length > 0) {
     checks.push({
+      id: 'MODULE_COMPAT',
       name: 'Modules',
       status: 'warning',
-      message: `${issues.length} incompatible module${issues.length > 1 ? 's' : ''}`,
+      message: `${issues.length} incompatible module${plural(issues.length)}`,
       details: issues,
+      suggestion: 'Update modules to versions compatible with your Nuxt version',
+      url: 'https://nuxt.com/modules',
     })
   }
   else if (moduleDetails.length > 0) {
     checks.push({
       name: 'Modules',
       status: 'success',
-      message: `${moduleDetails.length} module${moduleDetails.length > 1 ? 's' : ''} loaded`,
+      message: `${moduleDetails.length} module${plural(moduleDetails.length)} loaded`,
       details: moduleDetails,
     })
   }
@@ -247,20 +289,41 @@ async function checkModuleCompat(checks: DoctorCheck[], nuxt: Nuxt, cwd: string)
   }
 }
 
-function displayResults(checks: DoctorCheck[]): void {
+const statusStyles = {
+  success: { icon: '✓', color: colors.green, detailColor: colors.dim },
+  warning: { icon: '!', color: colors.yellow, detailColor: colors.yellow },
+  error: { icon: '✗', color: colors.red, detailColor: colors.red },
+} as const
+
+function displayResults(checks: DoctorCheck[], opts: { verbose?: boolean, json?: boolean }): void {
+  if (opts.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(checks))
+    return
+  }
+
   for (const check of checks) {
-    const icon = check.status === 'success' ? colors.green('✓') : check.status === 'warning' ? colors.yellow('!') : colors.red('✗')
+    const style = statusStyles[check.status]
+    const icon = style.color(style.icon)
     const source = check.source ? colors.gray(` (via ${check.source})`) : ''
     const name = colors.bold(check.name)
-    const message = check.status === 'error' ? colors.red(check.message) : check.status === 'warning' ? colors.yellow(check.message) : check.message
+    const message = check.status === 'success' ? check.message : style.color(check.message)
 
-    // Build output with details on same block
     let output = `[${icon}] ${name}${source} - ${message}`
 
-    if (check.details?.length) {
-      const detailColor = check.status === 'error' ? colors.red : check.status === 'warning' ? colors.yellow : colors.dim
-      for (const detail of check.details) {
-        output += `\n    ${detailColor('→')} ${detailColor(detail)}`
+    const details = [check.details ?? []].flat()
+    if (details.length) {
+      for (const detail of details)
+        output += `\n    ${style.detailColor('→')} ${style.detailColor(detail)}`
+    }
+
+    // Verbose: show suggestion and url
+    if (opts.verbose) {
+      if (check.suggestion) {
+        output += `\n    ${colors.cyan('💡')} ${colors.cyan(check.suggestion)}`
+      }
+      if (check.url) {
+        output += `\n    ${colors.blue('🔗')} ${colors.blue(check.url)}`
       }
     }