refactor: update node version requirements and enhance linting process with improved error handling

Author: aidenybai

packages/react-doctor/src/constants.ts

@@ -51,6 +51,10 @@ export const WARNING_ESTIMATED_FIX_RATE = 0.8;
 
 export const MAX_KNIP_RETRIES = 5;
 
+export const OXLINT_NODE_REQUIREMENT = "^20.19.0 || >=22.12.0";
+
+export const OXLINT_RECOMMENDED_NODE_MAJOR = 24;
+
 export const AMI_WEBSITE_URL = "https://ami.dev";
 
 export const AMI_INSTALL_URL = `${AMI_WEBSITE_URL}/install.sh`;

packages/react-doctor/src/scan.ts

@@ -7,6 +7,8 @@ import {
   MILLISECONDS_PER_SECOND,
   OFFLINE_FLAG_MESSAGE,
   OFFLINE_MESSAGE,
+  OXLINT_NODE_REQUIREMENT,
+  OXLINT_RECOMMENDED_NODE_MAJOR,
   PERFECT_SCORE,
   SCORE_BAR_WIDTH_CHARS,
   SCORE_GOOD_THRESHOLD,
@@ -31,6 +33,12 @@ import { highlighter } from "./utils/highlighter.js";
 import { indentMultilineText } from "./utils/indent-multiline-text.js";
 import { loadConfig } from "./utils/load-config.js";
 import { logger } from "./utils/logger.js";
+import { prompts } from "./utils/prompts.js";
+import {
+  installNodeViaNvm,
+  isNvmInstalled,
+  resolveNodeForOxlint,
+} from "./utils/resolve-compatible-node.js";
 import { runKnip } from "./utils/run-knip.js";
 import { runOxlint } from "./utils/run-oxlint.js";
 import { spinner } from "./utils/spinner.js";
@@ -331,6 +339,64 @@ const printSummary = (
   logger.dim(`  Share your results: ${highlighter.info(shareUrl)}`);
 };
 
+const resolveOxlintNode = async (
+  isLintEnabled: boolean,
+  isScoreOnly: boolean,
+): Promise<string | null> => {
+  if (!isLintEnabled) return null;
+
+  const nodeResolution = resolveNodeForOxlint();
+
+  if (nodeResolution) {
+    if (!nodeResolution.isCurrentNode && !isScoreOnly) {
+      logger.warn(
+        `Node ${process.version} is unsupported by oxlint. Using Node ${nodeResolution.version} from nvm.`,
+      );
+      logger.break();
+    }
+    return nodeResolution.binaryPath;
+  }
+
+  if (isScoreOnly) return null;
+
+  logger.warn(
+    `Node ${process.version} is not compatible with oxlint (requires ${OXLINT_NODE_REQUIREMENT}). Lint checks will be skipped.`,
+  );
+
+  if (isNvmInstalled() && process.stdin.isTTY) {
+    const { shouldInstallNode } = await prompts({
+      type: "confirm",
+      name: "shouldInstallNode",
+      message: `Install Node ${OXLINT_RECOMMENDED_NODE_MAJOR} via nvm to enable lint checks?`,
+      initial: true,
+    });
+
+    if (shouldInstallNode) {
+      logger.break();
+      const freshResolution = installNodeViaNvm() ? resolveNodeForOxlint() : null;
+      if (freshResolution) {
+        logger.break();
+        logger.success(`Node ${freshResolution.version} installed. Using it for lint checks.`);
+        logger.break();
+        return freshResolution.binaryPath;
+      }
+      logger.break();
+      logger.warn("Failed to install Node via nvm. Skipping lint checks.");
+      logger.break();
+      return null;
+    }
+  } else if (isNvmInstalled()) {
+    logger.dim(`  Run: nvm install ${OXLINT_RECOMMENDED_NODE_MAJOR}`);
+  } else {
+    logger.dim(
+      `  Install nvm (https://github.com/nvm-sh/nvm) and run: nvm install ${OXLINT_RECOMMENDED_NODE_MAJOR}`,
+    );
+  }
+
+  logger.break();
+  return null;
+};
+
 interface ResolvedScanOptions {
   lint: boolean;
   deadCode: boolean;
@@ -411,7 +477,10 @@ export const scan = async (
   let didLintFail = false;
   let didDeadCodeFail = false;
 
-  const lintPromise = options.lint
+  const resolvedNodeBinaryPath = await resolveOxlintNode(options.lint, options.scoreOnly);
+  if (options.lint && !resolvedNodeBinaryPath) didLintFail = true;
+
+  const lintPromise = resolvedNodeBinaryPath
     ? (async () => {
         const lintSpinner = options.scoreOnly ? null : spinner("Running lint checks...").start();
         try {
@@ -421,19 +490,25 @@ export const scan = async (
             projectInfo.framework,
             projectInfo.hasReactCompiler,
             jsxIncludePaths,
+            resolvedNodeBinaryPath,
           );
           lintSpinner?.succeed("Running lint checks.");
           return lintDiagnostics;
         } catch (error) {
           didLintFail = true;
-          lintSpinner?.fail("Lint checks failed (non-fatal, skipping).");
-          if (error instanceof Error) {
-            logger.error(error.message);
-            if (error.stack) {
-              logger.dim(error.stack);
-            }
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          const isNativeBindingError = errorMessage.includes("native binding");
+
+          if (isNativeBindingError) {
+            lintSpinner?.fail(
+              `Lint checks failed — oxlint native binding not found (Node ${process.version}).`,
+            );
+            logger.dim(
+              `  Upgrade to Node ${OXLINT_NODE_REQUIREMENT} or run: npx -p oxlint@latest react-doctor@latest`,
+            );
           } else {
-            logger.error(String(error));
+            lintSpinner?.fail("Lint checks failed (non-fatal, skipping).");
+            logger.error(errorMessage);
           }
           return [];
         }

packages/react-doctor/src/utils/resolve-compatible-node.ts

@@ -0,0 +1,113 @@
+import { execSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { OXLINT_RECOMMENDED_NODE_MAJOR } from "../constants.js";
+
+interface NodeVersion {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+interface NodeResolution {
+  binaryPath: string;
+  isCurrentNode: boolean;
+  version: string;
+}
+
+const parseNodeVersion = (versionString: string): NodeVersion => {
+  const cleaned = versionString.replace(/^v/, "").trim();
+  const [major = 0, minor = 0, patch = 0] = cleaned.split(".").map(Number);
+  return { major, minor, patch };
+};
+
+const isNodeVersionCompatibleWithOxlint = ({ major, minor }: NodeVersion): boolean => {
+  if (major === 20 && minor >= 19) return true;
+  if (major === 22 && minor >= 12) return true;
+  if (major > 22) return true;
+  return false;
+};
+
+const isCurrentNodeCompatibleWithOxlint = (): boolean =>
+  isNodeVersionCompatibleWithOxlint(parseNodeVersion(process.version));
+
+const getNvmDirectory = (): string | null => {
+  const envNvmDirectory = process.env.NVM_DIR;
+  if (envNvmDirectory && existsSync(envNvmDirectory)) return envNvmDirectory;
+
+  const defaultNvmDirectory = path.join(os.homedir(), ".nvm");
+  if (existsSync(defaultNvmDirectory)) return defaultNvmDirectory;
+
+  return null;
+};
+
+export const isNvmInstalled = (): boolean => getNvmDirectory() !== null;
+
+const findCompatibleNvmBinary = (): string | null => {
+  const nvmDirectory = getNvmDirectory();
+  if (!nvmDirectory) return null;
+
+  const versionsDirectory = path.join(nvmDirectory, "versions", "node");
+  if (!existsSync(versionsDirectory)) return null;
+
+  const compatibleVersions = readdirSync(versionsDirectory)
+    .filter((directoryName) => directoryName.startsWith("v"))
+    .map((directoryName) => ({ directoryName, ...parseNodeVersion(directoryName) }))
+    .filter((version) => isNodeVersionCompatibleWithOxlint(version))
+    .sort(
+      (versionA, versionB) =>
+        versionB.major - versionA.major ||
+        versionB.minor - versionA.minor ||
+        versionB.patch - versionA.patch,
+    );
+
+  if (compatibleVersions.length === 0) return null;
+
+  const bestVersion = compatibleVersions[0];
+  const binaryPath = path.join(versionsDirectory, bestVersion.directoryName, "bin", "node");
+  return existsSync(binaryPath) ? binaryPath : null;
+};
+
+const getNodeVersionFromBinary = (binaryPath: string): string | null => {
+  try {
+    return execSync(`"${binaryPath}" --version`, { encoding: "utf-8" }).trim();
+  } catch {
+    return null;
+  }
+};
+
+export const installNodeViaNvm = (): boolean => {
+  const nvmDirectory = getNvmDirectory();
+  if (!nvmDirectory) return false;
+
+  const nvmScript = path.join(nvmDirectory, "nvm.sh");
+  if (!existsSync(nvmScript)) return false;
+
+  try {
+    execSync(`bash -c ". '${nvmScript}' && nvm install ${OXLINT_RECOMMENDED_NODE_MAJOR}"`, {
+      stdio: "inherit",
+    });
+    return findCompatibleNvmBinary() !== null;
+  } catch {
+    return false;
+  }
+};
+
+export const resolveNodeForOxlint = (): NodeResolution | null => {
+  if (isCurrentNodeCompatibleWithOxlint()) {
+    return {
+      binaryPath: process.execPath,
+      isCurrentNode: true,
+      version: process.version,
+    };
+  }
+
+  const nvmBinaryPath = findCompatibleNvmBinary();
+  if (!nvmBinaryPath) return null;
+
+  const version = getNodeVersionFromBinary(nvmBinaryPath);
+  if (!version) return null;
+
+  return { binaryPath: nvmBinaryPath, isCurrentNode: false, version };
+};

packages/react-doctor/src/utils/run-oxlint.ts

@@ -283,9 +283,13 @@ const batchIncludePaths = (baseArgs: string[], includePaths: string[]): string[]
   return batches;
 };
 
-const spawnOxlint = (args: string[], rootDirectory: string): Promise<string> =>
+const spawnOxlint = (
+  args: string[],
+  rootDirectory: string,
+  nodeBinaryPath: string,
+): Promise<string> =>
   new Promise<string>((resolve, reject) => {
-    const child = spawn(process.execPath, args, {
+    const child = spawn(nodeBinaryPath, args, {
       cwd: rootDirectory,
     });
 
@@ -349,6 +353,7 @@ export const runOxlint = async (
   framework: Framework,
   hasReactCompiler: boolean,
   includePaths?: string[],
+  nodeBinaryPath: string = process.execPath,
 ): Promise<Diagnostic[]> => {
   if (includePaths !== undefined && includePaths.length === 0) {
     return [];
@@ -375,7 +380,7 @@ export const runOxlint = async (
     const allDiagnostics: Diagnostic[] = [];
     for (const batch of fileBatches) {
       const batchArgs = [...baseArgs, ...batch];
-      const stdout = await spawnOxlint(batchArgs, rootDirectory);
+      const stdout = await spawnOxlint(batchArgs, rootDirectory, nodeBinaryPath);
       allDiagnostics.push(...parseOxlintOutput(stdout));
     }