@santi020k/eslint-config-basic 3.1.0 → 3.3.0

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
+import { createRequire, findPackageJSON } from "node:module";
 import { basename, dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { findTailwindEntryPoint } from "@santi020k/eslint-config-core";
 import {
   analyzeEslintConfig,
   ESLINT_CONFIG_FILENAMES,
@@ -11,6 +12,16 @@ import {
 } from "./agent-skill-generator.js";
 import { handleCompatibility, handleExplainRule } from "./cli-advanced.js";
 import { getExplicitConfigFeaturePackages, handleMigrateV3 } from "./cli-migration.js";
+import {
+  addCompatibleConfigVersions,
+  createInstallCommand,
+  createInstallInvocation,
+  detectPackageManager,
+  findPnpmWorkspaceRoot,
+  getCatalogPreference,
+  getCompatibleConfigVersion
+} from "./cli-package-manager.js";
+import { handleExplainPreset } from "./cli-preset.js";
 import {
   handleBaseline,
   handleProfile,
@@ -18,6 +29,7 @@ import {
   handleSnapshotDiff
 } from "./cli-workflows.js";
 import { detectProjectOptions } from "./index.js";
+import { findCssComponentClasses } from "./tailwind.js";
 const getDefaultConfigFilename = (cwd) => {
   const packageJsonPath = join(cwd, "package.json");
   if (!existsSync(packageJsonPath)) return "eslint.config.mjs";
@@ -80,6 +92,13 @@ const CATEGORY_PACKAGES = {
   testing: "@santi020k/eslint-config-testing",
   tools: "@santi020k/eslint-config-tools"
 };
+const PRESET_INSTALL_PACKAGES = {
+  all: Object.values(CATEGORY_PACKAGES),
+  app: [CATEGORY_PACKAGES.testing, CATEGORY_PACKAGES.tools],
+  ci: [CATEGORY_PACKAGES.extensions, CATEGORY_PACKAGES.tools],
+  library: [CATEGORY_PACKAGES.extensions, CATEGORY_PACKAGES.tools],
+  monorepo: [CATEGORY_PACKAGES.extensions, CATEGORY_PACKAGES.tools]
+};
 const getConfigPathIfPresent = (cwd) => {
   const configPath = ESLINT_CONFIG_FILENAMES.map((filename) => join(cwd, filename)).find((p) => existsSync(p));
   return configPath ?? null;
@@ -153,41 +172,13 @@ const getInstallPackages = (summary, declaredDependencies, explicitFeaturePackag
     for (const packageName of explicitFeaturePackages) {
       packages.add(packageName);
     }
+    for (const packageName of PRESET_INSTALL_PACKAGES[summary.preset] ?? []) {
+      packages.add(packageName);
+    }
   }
   if (summary.typescript) packages.add(TYPESCRIPT_PACKAGE_NAME);
   return [...packages].filter((packageName) => !declaredDependencies.has(packageName));
 };
-const createInstallCommand = (packageManager, packages, workspaceRoot = false) => {
-  const packageList = packages.join(" ");
-  switch (packageManager) {
-    case "bun":
-      return `bun add -d ${packageList}`;
-    case "npm":
-      return `npm install -D ${packageList}`;
-    case "yarn":
-      return `yarn add -D ${packageList}`;
-    default:
-      return `pnpm add -D${workspaceRoot ? " --workspace-root" : ""} ${packageList}`;
-  }
-};
-const createInstallInvocation = (packageManager, packages, workspaceRoot = false) => {
-  switch (packageManager) {
-    case "bun":
-      return ["bun", ["add", "-d", ...packages]];
-    case "npm":
-      return ["npm", ["install", "-D", ...packages]];
-    case "yarn":
-      return ["yarn", ["add", "-D", ...packages]];
-    default:
-      return ["pnpm", ["add", "-D", ...workspaceRoot ? ["--workspace-root"] : [], ...packages]];
-  }
-};
-const detectPackageManager = (cwd) => {
-  if (existsSync(join(cwd, "pnpm-lock.yaml")) || existsSync(join(cwd, "pnpm-workspace.yaml"))) return "pnpm";
-  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock"))) return "bun";
-  return "npm";
-};
 const hasLintScript = (cwd) => {
   const packageJson = readPackageJson(cwd);
   return Boolean(packageJson?.scripts?.lint);
@@ -237,13 +228,13 @@ const detectWorkspaceProjects = (cwd) => {
 const createExplicitOptions = (cwd) => {
   const summary = getProjectSummary(cwd);
   const options = [];
-  const optionalCategories = [
-    ["libraries", summary.libraries],
-    ["testing", summary.testing],
-    ["formats", summary.formats],
-    ["tools", summary.tools],
-    ["extensions", summary.extensions]
-  ];
+  const features = [.../* @__PURE__ */ new Set([
+    ...summary.extensions,
+    ...summary.formats,
+    ...summary.libraries,
+    ...summary.testing,
+    ...summary.tools
+  ])].sort();
   if (summary.typescript) options.push("  typescript: true,");
   if (summary.frameworks.length > 0) {
     options.push(
@@ -252,10 +243,12 @@ const createExplicitOptions = (cwd) => {
       "  },"
     );
   }
-  for (const [category, values] of optionalCategories) {
-    if (values.length > 0) {
-      options.push(`  ${category}: ${JSON.stringify(values)},`);
-    }
+  if (features.length > 0) {
+    options.push(
+      "  features: {",
+      ...features.map((feature) => `    ${toPropertyKey(feature)}: true,`),
+      "  },"
+    );
   }
   return options;
 };
@@ -280,6 +273,10 @@ const formatList = (values) => {
 const getProjectSummary = (cwd) => {
   const options = detectProjectOptions(cwd);
   const workspaceProjects = detectWorkspaceProjects(cwd);
+  let typescriptMode = "off";
+  if (options.typescript) {
+    typescriptMode = options.typescript === "syntax" ? "syntax" : "type-aware";
+  }
   return {
     detectedProjects: Object.keys(options.projects ?? {}).sort(),
     extensions: options.extensions ?? [],
@@ -292,13 +289,56 @@ const getProjectSummary = (cwd) => {
     testing: options.testing ?? [],
     tools: options.tools ?? [],
     typescript: Boolean(options.typescript),
+    typescriptMode,
     workspaceProjects
   };
 };
+const getDetectedProjectPaths = (cwd) => {
+  const summary = getProjectSummary(cwd);
+  return summary.workspaceProjects.length > 0 ? [.../* @__PURE__ */ new Set([...summary.detectedProjects, ...summary.workspaceProjects])] : ["."];
+};
+const getTailwindUnknownClassPolicy = (detected, entryPoint, componentClasses = 0) => {
+  if (!detected) return "off";
+  if (!entryPoint) return "fallback-off";
+  return componentClasses > 0 ? "strict-with-css-components" : "strict";
+};
+const getTailwindEntryPoints = (cwd) => getDetectedProjectPaths(cwd).flatMap((projectPath) => {
+  const projectRoot = projectPath === "." ? cwd : join(cwd, projectPath);
+  const summary = getProjectSummary(projectRoot);
+  if (!summary.libraries.includes("tailwind")) return [];
+  const entryPoint = findTailwindEntryPoint(projectRoot) ?? null;
+  const componentClasses = entryPoint ? findCssComponentClasses(projectRoot, entryPoint).length : 0;
+  return [{
+    componentClasses,
+    entryPoint,
+    path: projectPath,
+    unknownClassPolicy: getTailwindUnknownClassPolicy(true, entryPoint, componentClasses)
+  }];
+});
+const getDeclarationProjectWarnings = (cwd) => getDetectedProjectPaths(cwd).flatMap((projectPath) => {
+  const projectRoot = projectPath === "." ? cwd : join(cwd, projectPath);
+  const summary = getProjectSummary(projectRoot);
+  if (summary.typescriptMode !== "syntax") return [];
+  const packageName = readPackageJson(projectRoot)?.name;
+  const packageLabel = typeof packageName === "string" ? `${projectPath} (${packageName})` : projectPath;
+  return [
+    `TypeScript declarations were detected in ${packageLabel}, but no supported package-local tsconfig was found. The package uses syntax-only linting to avoid a project-service parse failure. Add a tsconfig.json that includes the declarations for type-aware linting, or add their patterns to \`typescript.untypedFiles\` when a parent type-aware project intentionally owns them.`
+  ];
+});
 const getInstallProjectSummary = (cwd) => {
   const rootSummary = getProjectSummary(cwd);
-  const projectSummaries = rootSummary.detectedProjects.map((projectPath) => getProjectSummary(join(cwd, projectPath)));
+  const projectPaths = [.../* @__PURE__ */ new Set([
+    ...rootSummary.detectedProjects,
+    ...rootSummary.workspaceProjects
+  ])];
+  const projectSummaries = projectPaths.map((projectPath) => getProjectSummary(join(cwd, projectPath)));
   const summaries = [rootSummary, ...projectSummaries];
+  let typescriptMode = "off";
+  if (summaries.some((summary) => summary.typescriptMode === "type-aware")) {
+    typescriptMode = "type-aware";
+  } else if (summaries.some((summary) => summary.typescriptMode === "syntax")) {
+    typescriptMode = "syntax";
+  }
   return {
     ...rootSummary,
     extensions: [...new Set(summaries.flatMap((summary) => summary.extensions))],
@@ -307,7 +347,8 @@ const getInstallProjectSummary = (cwd) => {
     libraries: [...new Set(summaries.flatMap((summary) => summary.libraries))],
     testing: [...new Set(summaries.flatMap((summary) => summary.testing))],
     tools: [...new Set(summaries.flatMap((summary) => summary.tools))],
-    typescript: summaries.some((summary) => summary.typescript)
+    typescript: summaries.some((summary) => summary.typescript),
+    typescriptMode
   };
 };
 const getWorkspaceDeclaredConfigPackages = (cwd, summary) => {
@@ -368,6 +409,7 @@ const printUsage = () => {
     "  init            Create eslint.config.js/mjs if missing",
     "  update          Regenerate eslint.config.js/mjs from detection",
     "  explain         Print detected v3 config inputs",
+    "  explain-preset  Compare the current config with a preset",
     "  inspect         Print detected inputs and active config features",
     "  install         Install missing packages for detected v3 features",
     "  doctor          Check project setup for common v3 adoption issues",
@@ -381,13 +423,14 @@ const printUsage = () => {
     "  generate-skill  Generate AI agent standards files",
     "",
     "Options:",
+    "  --analyze-source explain-preset: lint source and preview autofix without writing",
     "  --force         Overwrite existing generated skill sections/files",
     "  --check         Verify generated files, migrations, or snapshots without writing",
     "  --concurrency   profile: off, auto, or a worker count",
     "  --create        generate-skill: scaffold a root AGENTS.md when missing",
     "  --dry-run       install: print the detected install command without running it",
     "  --explicit      init: write detected settings explicitly",
-    "  --file          profile/snapshot/diff: representative file or lint target (repeatable)",
+    "  --file          explain/explain-preset/profile/snapshot/diff: file or lint target (repeatable)",
     "  --fix           doctor: safely repair generated config and package metadata",
     "  --full          migrate --to v3: choose the batteries-included package",
     "  --json          Print JSON for commands that support it",
@@ -395,16 +438,107 @@ const printUsage = () => {
     "  --max-duration  profile: maximum duration in milliseconds",
     "  --max-rule-time profile: maximum time for the slowest rule in milliseconds",
     "  --max-warnings  profile: maximum warning count",
+    "  --compatibility explain-preset: write a temporary compatibility override",
+    "  --output        explain-preset: compatibility override path",
     "  --preset        baseline: enable ci or pedantic strict mode before suppressing",
     "  --prune         baseline: remove suppressions for resolved violations",
     "  --snapshot-path snapshot/diff: override .eslint-config-snapshot.json",
     "  --to            migrate: target version (v2 or v3)",
+    "  --verbose       doctor: print per-project activation details",
     "  --with-eslint-mcp generate-skill: scaffold the official ESLint MCP server",
     "  --write         Apply safe migrations for commands that support it",
     "  --help, -h      Show this help message",
     "  --version, -v   Show CLI version"
   ].join("\n"));
 };
+const COMMAND_OPTIONS = {
+  baseline: ["--json", "--preset", "--prune"],
+  compatibility: ["--json"],
+  diff: ["--file", "--json", "--snapshot-path"],
+  docs: [],
+  doctor: ["--fix", "--json", "--lite-install", "--verbose"],
+  explain: ["--file", "--json"],
+  "explain-preset": ["--analyze-source", "--compatibility", "--file", "--json", "--output"],
+  "generate-skill": ["--check", "--create", "--force", "--with-eslint-mcp"],
+  init: ["--check", "--explicit"],
+  inspect: ["--json"],
+  install: ["--dry-run"],
+  migrate: ["--check", "--full", "--json", "--to", "--write"],
+  profile: ["--concurrency", "--file", "--json", "--max-duration", "--max-rule-time", "--max-warnings"],
+  snapshot: ["--check", "--file", "--json", "--snapshot-path"],
+  update: []
+};
+const VALUE_OPTIONS = /* @__PURE__ */ new Set([
+  "--concurrency",
+  "--file",
+  "--max-duration",
+  "--max-rule-time",
+  "--max-warnings",
+  "--output",
+  "--preset",
+  "--snapshot-path",
+  "--to"
+]);
+const printCommandUsage = (command) => {
+  let positional = "";
+  if (command === "explain") positional = " [rule]";
+  else if (command === "explain-preset") positional = " <preset>";
+  const options = COMMAND_OPTIONS[command] ?? [];
+  console.log([
+    "Usage: basic-eslint <command> [options]",
+    "",
+    `Usage: basic-eslint ${command}${positional}${options.length > 0 ? " [options]" : ""}`,
+    ...options.length > 0 ? ["", "Options:", ...options.map((option) => `  ${option}`)] : []
+  ].join("\n"));
+};
+const validateCommandArguments = (command, args) => {
+  const allowed = COMMAND_OPTIONS[command];
+  if (!allowed) return { ok: true };
+  const allowedOptions = new Set(allowed);
+  const positionals = [];
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index];
+    if (!argument.startsWith("-")) {
+      positionals.push(argument);
+      continue;
+    }
+    const option = argument.includes("=") ? argument.slice(0, argument.indexOf("=")) : argument;
+    if (!allowedOptions.has(option)) {
+      console.error(`Unknown option for ${command}: ${option}`);
+      process.exitCode = 1;
+      return { ok: false };
+    }
+    if (argument.includes("=") && !VALUE_OPTIONS.has(option)) {
+      console.error(`Option ${option} does not accept a value.`);
+      process.exitCode = 1;
+      return { ok: false };
+    }
+    if (VALUE_OPTIONS.has(option) && !argument.includes("=")) {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        console.error(
+          ["--max-duration", "--max-rule-time", "--max-warnings"].includes(option) ? `${option} must be a non-negative number.` : `Option ${option} requires a value.`
+        );
+        process.exitCode = 1;
+        return { ok: false };
+      }
+      index++;
+    } else if (VALUE_OPTIONS.has(option) && argument.endsWith("=")) {
+      console.error(
+        ["--max-duration", "--max-rule-time", "--max-warnings"].includes(option) ? `${option} must be a non-negative number.` : `Option ${option} requires a value.`
+      );
+      process.exitCode = 1;
+      return { ok: false };
+    }
+  }
+  const maximumPositionals = command === "explain" || command === "explain-preset" ? 1 : 0;
+  if (positionals.length > maximumPositionals) {
+    console.error(`Unexpected argument for ${command}: ${positionals[maximumPositionals]}`);
+    process.exitCode = 1;
+    return { ok: false };
+  }
+  return { ok: true, positional: positionals[0] };
+};
 const handleInit = (cwd = process.cwd(), check = false, explicit = false) => {
   const configPath = resolveConfigPath(cwd);
   if (check) {
@@ -466,7 +600,8 @@ const handleInspect = async (cwd = process.cwd(), json = false) => {
   const payload = {
     activeConfig,
     detected: summary,
-    packageManager: detectPackageManager(cwd)
+    packageManager: detectPackageManager(cwd),
+    tailwindEntryPoints: getTailwindEntryPoints(cwd)
   };
   if (json) {
     console.log(JSON.stringify(payload, null, 2));
@@ -490,31 +625,135 @@ const handleInspect = async (cwd = process.cwd(), json = false) => {
   ].join("\n"));
 };
 const semver = createRequire(import.meta.url)("semver");
-const readPackageMetadataFromMain = (mainPath, packageName) => {
+const intersectTwoSemverRanges = (left, right) => {
+  if (semver.subset(left, right)) return left;
+  if (semver.subset(right, left)) return right;
+  const intersections = /* @__PURE__ */ new Set();
+  const leftRange = new semver.Range(left);
+  const rightRange = new semver.Range(right);
+  for (const leftComparators of leftRange.set) {
+    for (const rightComparators of rightRange.set) {
+      const candidate = [...leftComparators, ...rightComparators].map((comparator) => comparator.value).filter(Boolean).join(" ");
+      const normalized = new semver.Range(candidate || "*").range || "*";
+      if (semver.minVersion(normalized)) intersections.add(normalized);
+    }
+  }
+  return intersections.size > 0 ? [...intersections].join(" || ") : null;
+};
+const intersectSemverRanges = (ranges) => {
+  const validRanges = ranges.filter((range) => semver.validRange(range) !== null);
+  if (validRanges.length !== ranges.length || validRanges.length === 0) return null;
+  let intersection = validRanges[0];
+  for (const range of validRanges.slice(1)) {
+    intersection = intersectTwoSemverRanges(intersection, range) ?? "";
+    if (!intersection) return null;
+  }
+  return intersection;
+};
+const readPackageMetadataFromMain = (mainPath) => {
   let directory = dirname(mainPath);
   for (let depth = 0; depth < 4; depth++) {
     const packagePath = join(directory, "package.json");
     if (existsSync(packagePath)) {
       const metadata = JSON.parse(readFileSync(packagePath, "utf8"));
-      if (metadata.name === packageName) return metadata;
+      if (metadata.name && metadata.version) return metadata;
     }
     directory = dirname(directory);
   }
   return null;
 };
 const resolvePackageMetadata = (cwd, packageName) => {
-  try {
-    const projectRequire = createRequire(join(cwd, "package.json"));
+  const candidateRoots = [...new Set([
+    cwd,
+    findPnpmWorkspaceRoot(cwd)
+  ].filter((root) => Boolean(root)))];
+  for (const candidateRoot of candidateRoots) {
     try {
-      return readPackageMetadataFromMain(projectRequire.resolve(packageName), packageName);
+      const manifestPath = findPackageJSON(
+        packageName,
+        pathToFileURL(join(candidateRoot, "package.json"))
+      );
+      if (manifestPath) {
+        const metadata = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return metadata;
+      }
     } catch {
-      const integrationsMain = projectRequire.resolve(INTEGRATIONS_PACKAGE_NAME);
-      const integrationsRequire = createRequire(integrationsMain);
-      return readPackageMetadataFromMain(integrationsRequire.resolve(packageName), packageName);
     }
-  } catch {
-    return null;
+    try {
+      const projectRequire = createRequire(join(candidateRoot, "package.json"));
+      try {
+        const metadata = readPackageMetadataFromMain(projectRequire.resolve(packageName));
+        if (metadata) return metadata;
+      } catch {
+        const integrationsMain = projectRequire.resolve(INTEGRATIONS_PACKAGE_NAME);
+        const integrationsRequire = createRequire(integrationsMain);
+        const metadata = readPackageMetadataFromMain(integrationsRequire.resolve(packageName));
+        if (metadata) return metadata;
+      }
+    } catch {
+    }
+    for (const projectPath of detectWorkspaceProjects(candidateRoot)) {
+      const metadata = readPackageJson(join(candidateRoot, projectPath));
+      if (metadata?.name === packageName) return metadata;
+    }
+  }
+  return null;
+};
+const assessConsumerNodeEngine = (cwd, packageJson) => {
+  const declaredConfigPackages = [...getDeclaredDependencyNames(packageJson)].filter((packageName) => packageName.startsWith("@santi020k/eslint-config-"));
+  const requiredRanges = declaredConfigPackages.flatMap((packageName) => {
+    const range = resolvePackageMetadata(cwd, packageName)?.engines?.node;
+    return range ? [range] : [];
+  });
+  const requiredRange = intersectSemverRanges(requiredRanges);
+  const engines = packageJson?.engines;
+  const consumerRange = engines && typeof engines === "object" && !Array.isArray(engines) ? engines.node : null;
+  const normalizedConsumerRange = typeof consumerRange === "string" ? consumerRange : null;
+  if (requiredRanges.length === 0) {
+    return {
+      compatible: true,
+      consumerRange: normalizedConsumerRange,
+      requiredRange: null,
+      targetRange: null
+    };
+  }
+  if (!requiredRange) {
+    return {
+      compatible: false,
+      consumerRange: normalizedConsumerRange,
+      requiredRange: null,
+      targetRange: null
+    };
   }
+  if (!normalizedConsumerRange || !semver.validRange(normalizedConsumerRange)) {
+    return {
+      compatible: false,
+      consumerRange: normalizedConsumerRange,
+      requiredRange,
+      targetRange: requiredRange
+    };
+  }
+  const compatible = requiredRanges.every((range) => semver.subset(normalizedConsumerRange, range));
+  return {
+    compatible,
+    consumerRange: normalizedConsumerRange,
+    requiredRange,
+    targetRange: compatible ? null : intersectSemverRanges([normalizedConsumerRange, ...requiredRanges])
+  };
+};
+const getConsumerNodeEngineWarning = (cwd, packageJson) => {
+  const assessment = assessConsumerNodeEngine(cwd, packageJson);
+  if (assessment.compatible) return null;
+  if (!assessment.requiredRange) {
+    return "Installed config packages do not share a compatible Node engine range.";
+  }
+  if (!assessment.consumerRange) {
+    return `package.json does not declare engines.node; installed config packages require ${assessment.requiredRange}.`;
+  }
+  if (!semver.validRange(assessment.consumerRange)) {
+    return `package.json engines.node ${assessment.consumerRange} is invalid; installed config packages require ${assessment.requiredRange}.`;
+  }
+  return `package.json engines.node ${assessment.consumerRange} permits unsupported runtimes; installed config packages require ${assessment.requiredRange}.`;
 };
 const getAstroDoctorNodeWarning = (metadata) => {
   const nodeRange = metadata.engines?.node;
@@ -562,7 +801,11 @@ const validateConfigContent = (configContent, hasV1FrameworkImports, declaredDep
   if (hasV1FrameworkImports) {
     warnings.push("Config still imports v1 framework packages. Run `basic-eslint migrate --write` or switch to framework booleans.");
   }
-  const usesBasicComposer = /from\s*['"]@santi020k\/eslint-config-(?:basic|full|lite)['"]/.test(configContent) && /\b(?:defineConfig|eslintConfig)\s*\(/.test(configContent);
+  const usesComposerCall = /from\s*['"]@santi020k\/eslint-config-(?:basic|full|lite)['"]/.test(configContent) && /\b(?:defineConfig|eslintConfig)\s*\(/.test(configContent);
+  const usesRecommendedComposer = /from\s*['"]@santi020k\/eslint-config-(?:basic|full)\/recommended['"]/.test(
+    configContent
+  );
+  const usesBasicComposer = usesComposerCall || usesRecommendedComposer;
   const hasDetectedProjectScopes = summary.workspaceProjects.every((project) => summary.detectedProjects.includes(project));
   if (summary.workspaceProjects.length > 0 && !configContent.includes("projects:") && !(usesBasicComposer && hasDetectedProjectScopes)) {
     warnings.push("Workspace packages were detected, but the root config does not use `projects` scoping.");
@@ -585,6 +828,16 @@ const validateConfigContent = (configContent, hasV1FrameworkImports, declaredDep
       );
     }
   }
+  const missingPackages = getInstallPackages(
+    summary,
+    declaredDependencies,
+    getExplicitConfigFeaturePackages(configContent)
+  );
+  if (missingPackages.length > 0) {
+    warnings.push(
+      `The active configuration requires undeclared packages: ${missingPackages.join(", ")}. Run \`basic-eslint install\` to add the modular v3 dependency set.`
+    );
+  }
   return warnings;
 };
 const validateProjectSetup = (cwd, configPath, activeConfig, hasV1FrameworkImports) => {
@@ -634,7 +887,13 @@ const checkDuplicateEslint = (cwd, warnings) => {
     );
   }
 };
-const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary) => {
+const getTailwindEntryPointWarnings = (cwd) => getTailwindEntryPoints(cwd).flatMap(({ entryPoint, path: projectPath }) => {
+  if (entryPoint) return [];
+  return [
+    `Tailwind CSS was detected in ${projectPath}, but no conventional CSS entry point was found. \`better-tailwindcss/no-unknown-classes\` falls back to off; set \`tailwind.entryPoint\` to enable strict validation or \`tailwind.noUnknownClasses: false\` to document a mixed CSS system.`
+  ];
+});
+const buildDoctorDiagnosis = (cwd, packageJson, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary) => {
   const { issues, warnings } = validateProjectSetup(cwd, configPath, activeConfig, hasV1FrameworkImports);
   if (configContent) {
     warnings.push(...validateConfigContent(configContent, hasV1FrameworkImports, declaredDependencies, summary));
@@ -642,9 +901,238 @@ const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImpo
   const astroDoctorEnabled = checkAstroDoctorStatus(activeConfig, configContent, summary, warnings);
   warnings.push(...getAstroDoctorCompatibilityWarnings(cwd, astroDoctorEnabled));
   checkDuplicateEslint(cwd, warnings);
+  warnings.push(...getDeclarationProjectWarnings(cwd));
+  warnings.push(...getTailwindEntryPointWarnings(cwd));
+  const nodeEngineWarning = getConsumerNodeEngineWarning(cwd, packageJson);
+  if (nodeEngineWarning) warnings.push(nodeEngineWarning);
   return { issues, warnings };
 };
-const outputDoctorResult = (json, configPath, packageManager, summary, liteInstallCommand, issues, warnings, fixes = []) => {
+const DOCTOR_FEATURE_ALIASES = {
+  "astro-doctor": "Astro Doctor",
+  "best-practices": "Best Practices",
+  compat: "Browser Compat",
+  nest: "NestJS",
+  next: "Next.js",
+  node: "Node.js",
+  solid: "SolidJS",
+  "tanstack-start": "TanStack Start",
+  tailwind: "Tailwind CSS"
+};
+const normalizeDoctorFeature = (value) => {
+  const comparableValue = DOCTOR_FEATURE_ALIASES[value] ?? value;
+  return comparableValue.toLowerCase().replaceAll(/[^a-z0-9]/g, "");
+};
+const isDoctorFeatureEnabled = (name, enabled) => {
+  const normalizedName = normalizeDoctorFeature(name);
+  return enabled.some((value) => normalizeDoctorFeature(value) === normalizedName);
+};
+const getTypeScriptConfig = (cwd) => [
+  "tsconfig.json",
+  "tsconfig.base.json",
+  "tsconfig.app.json",
+  "tsconfig.node.json",
+  "tsconfig.eslint.json"
+].find((fileName) => existsSync(join(cwd, fileName))) ?? null;
+const getCategoryPackageInstalled = (cwd, packageName) => [
+  packageName,
+  INTEGRATIONS_PACKAGE_NAME,
+  FULL_PACKAGE_NAME
+].some((candidate) => resolvePackageMetadata(cwd, candidate) !== null);
+const createDoctorFeatureActivations = (cwd, category, detected, enabled, includeEnabled = false) => {
+  const names = [...detected];
+  if (includeEnabled) {
+    for (const enabledName of enabled) {
+      if (!isDoctorFeatureEnabled(enabledName, names)) names.push(enabledName);
+    }
+  }
+  return names.map((name) => {
+    const packageName = category === "frameworks" ? Object.entries(FRAMEWORK_KEY_TO_PACKAGE).find(([framework]) => isDoctorFeatureEnabled(name, [framework]))?.[1] : CATEGORY_PACKAGES[category];
+    if (!packageName) throw new Error(`Unknown doctor ${category} feature: ${name}`);
+    const installed = getCategoryPackageInstalled(cwd, packageName);
+    const isDetected = isDoctorFeatureEnabled(name, detected);
+    const isEnabled = installed && isDoctorFeatureEnabled(name, enabled);
+    let reason;
+    if (!installed) {
+      reason = isDetected ? `Detected, but ${packageName} is not installed.` : `Enabled in the active config, but ${packageName} is not installed.`;
+    } else if (!isEnabled) {
+      reason = "Detected and installed, but the active config did not load this pack.";
+    }
+    return {
+      detected: isDetected,
+      enabled: isEnabled,
+      installed,
+      name,
+      package: packageName,
+      ...reason ? { reason } : {}
+    };
+  });
+};
+const getInactiveDoctorPackages = (cwd, detectedFrameworks, summary, activeConfig) => {
+  const inactivePackages = Object.entries(FRAMEWORK_KEY_TO_PACKAGE).filter(([framework, packageName]) => !detectedFrameworks.includes(framework) && !isDoctorFeatureEnabled(framework, activeConfig?.frameworks ?? []) && resolvePackageMetadata(cwd, packageName) !== null).map(([, packageName]) => ({
+    package: packageName,
+    reason: "Installed, but no matching framework signal was detected in this project."
+  }));
+  for (const [category, packageName] of Object.entries(CATEGORY_PACKAGES)) {
+    if (summary[category].length === 0 && (activeConfig?.[category]?.length ?? 0) === 0 && resolvePackageMetadata(cwd, packageName) !== null) {
+      inactivePackages.push({
+        package: packageName,
+        reason: `Installed, but no ${category} signals were detected in this project.`
+      });
+    }
+  }
+  return inactivePackages;
+};
+const getDoctorProjectActivations = async (cwd) => {
+  const rootSummary = getProjectSummary(cwd);
+  const projectPaths = [.../* @__PURE__ */ new Set([
+    ".",
+    ...rootSummary.detectedProjects,
+    ...rootSummary.workspaceProjects
+  ])].sort((left, right) => {
+    if (left === ".") return -1;
+    if (right === ".") return 1;
+    return left.localeCompare(right);
+  });
+  return Promise.all(projectPaths.map(async (projectPath) => {
+    const projectRoot = projectPath === "." ? cwd : join(cwd, projectPath);
+    const summary = getProjectSummary(projectRoot);
+    const projectActiveConfig = await analyzeEslintConfig(cwd, { projectPath, projectPaths }) ?? void 0;
+    const tsconfig = getTypeScriptConfig(projectRoot);
+    const typescriptInstalled = resolvePackageMetadata(projectRoot, TYPESCRIPT_PACKAGE_NAME) !== null;
+    const typescriptEnabled = summary.typescript && Boolean(projectActiveConfig?.typescript);
+    const tailwindDetected = summary.libraries.includes("tailwind");
+    const tailwindEntryPoint = tailwindDetected ? findTailwindEntryPoint(projectRoot) ?? null : null;
+    const tailwindComponentClasses = tailwindEntryPoint ? findCssComponentClasses(projectRoot, tailwindEntryPoint).length : 0;
+    let typescriptMode = "off";
+    let typescriptReason;
+    if (typescriptEnabled) {
+      typescriptMode = summary.typescriptMode;
+    }
+    if (!typescriptInstalled && summary.typescript) {
+      typescriptReason = summary.typescriptMode === "syntax" ? "TypeScript declarations were detected, but TypeScript is not installed." : "A tsconfig was detected, but TypeScript is not installed.";
+    } else if (typescriptInstalled && !summary.typescript) {
+      typescriptReason = "Installed, but no supported tsconfig was detected in this project.";
+    } else if (typescriptInstalled && summary.typescript && !typescriptEnabled) {
+      typescriptReason = "Detected and installed, but the active config did not enable TypeScript.";
+    }
+    return {
+      extensions: createDoctorFeatureActivations(
+        projectRoot,
+        "extensions",
+        summary.extensions,
+        projectActiveConfig?.extensions ?? [],
+        true
+      ),
+      formats: createDoctorFeatureActivations(
+        projectRoot,
+        "formats",
+        summary.formats,
+        projectActiveConfig?.formats ?? [],
+        true
+      ),
+      frameworks: createDoctorFeatureActivations(
+        projectRoot,
+        "frameworks",
+        summary.frameworks,
+        projectActiveConfig?.frameworks ?? [],
+        true
+      ),
+      ignores: projectActiveConfig?.ignores ?? [],
+      inactivePackages: getInactiveDoctorPackages(projectRoot, summary.frameworks, summary, projectActiveConfig),
+      libraries: createDoctorFeatureActivations(
+        projectRoot,
+        "libraries",
+        summary.libraries,
+        projectActiveConfig?.libraries ?? [],
+        true
+      ),
+      path: projectPath,
+      runtime: summary.runtime,
+      tailwind: {
+        componentClasses: tailwindComponentClasses,
+        detected: tailwindDetected,
+        entryPoint: tailwindEntryPoint,
+        unknownClassPolicy: getTailwindUnknownClassPolicy(
+          tailwindDetected,
+          tailwindEntryPoint,
+          tailwindComponentClasses
+        )
+      },
+      testing: createDoctorFeatureActivations(
+        projectRoot,
+        "testing",
+        summary.testing,
+        projectActiveConfig?.testing ?? [],
+        true
+      ),
+      tools: createDoctorFeatureActivations(
+        projectRoot,
+        "tools",
+        summary.tools,
+        projectActiveConfig?.tools ?? [],
+        true
+      ),
+      typescript: {
+        detected: summary.typescript,
+        enabled: typescriptEnabled,
+        installed: typescriptInstalled,
+        mode: typescriptMode,
+        package: TYPESCRIPT_PACKAGE_NAME,
+        ...typescriptReason ? { reason: typescriptReason } : {},
+        tsconfig
+      }
+    };
+  }));
+};
+const formatDoctorActivation = (features) => features.length === 0 ? "none" : features.map((feature) => {
+  const states = [
+    feature.installed ? "I" : "-",
+    feature.detected ? "D" : "-",
+    feature.enabled ? "E" : "-"
+  ].join("");
+  return `${feature.name}[${states}]`;
+}).join(",");
+const formatDoctorProjectTable = (projects) => [
+  "",
+  "Per-project activation (I=installed, D=detected, E=enabled):",
+  "Project | Runtime | TypeScript | Tailwind entry | Frameworks | Formats | Libraries | Extensions | Testing | Tools | Ignores",
+  "--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---",
+  ...projects.flatMap((project) => {
+    const typescriptStates = [
+      project.typescript.installed ? "I" : "-",
+      project.typescript.detected ? "D" : "-",
+      project.typescript.enabled ? "E" : "-"
+    ].join("");
+    const row = [
+      project.path,
+      project.runtime,
+      `${project.typescript.mode}:${project.typescript.tsconfig ?? "none"}[${typescriptStates}]`,
+      project.tailwind.componentClasses > 0 ? `${project.tailwind.entryPoint ?? "none"} (${project.tailwind.componentClasses} CSS classes)` : project.tailwind.entryPoint ?? "none",
+      formatDoctorActivation(project.frameworks),
+      formatDoctorActivation(project.formats),
+      formatDoctorActivation(project.libraries),
+      formatDoctorActivation(project.extensions),
+      formatDoctorActivation(project.testing),
+      formatDoctorActivation(project.tools),
+      formatList(project.ignores)
+    ].join(" | ");
+    const explanations = [
+      project.typescript.reason,
+      ...project.frameworks.map((feature) => feature.reason),
+      ...project.formats.map((feature) => feature.reason),
+      ...project.libraries.map((feature) => feature.reason),
+      ...project.extensions.map((feature) => feature.reason),
+      ...project.testing.map((feature) => feature.reason),
+      ...project.tools.map((feature) => feature.reason),
+      ...project.inactivePackages.map((item) => `${item.package}: ${item.reason}`)
+    ].filter((reason) => Boolean(reason));
+    return [
+      row,
+      ...explanations.map((reason) => `  ${project.path}: ${reason}`)
+    ];
+  })
+];
+const outputDoctorResult = (json, verbose, configPath, packageManager, summary, installCommand, requiredPackages, issues, warnings, projects, fixes = []) => {
   let status = "passed";
   if (issues.length > 0) {
     status = "failed";
@@ -654,9 +1142,11 @@ const outputDoctorResult = (json, configPath, packageManager, summary, liteInsta
   const payload = {
     configFile: configPath ? basename(configPath) : null,
     fixes,
+    ...installCommand ? { installCommand } : {},
     issues,
-    liteInstallCommand,
     packageManager,
+    projects,
+    requiredPackages,
     status,
     warnings,
     workspaceProjects: summary.workspaceProjects
@@ -671,6 +1161,9 @@ const outputDoctorResult = (json, configPath, packageManager, summary, liteInsta
     `- Package manager: ${payload.packageManager}`,
     `- Config file: ${payload.configFile ?? "none"}`,
     `- Workspace projects: ${formatList(summary.workspaceProjects)}`,
+    `- Required packages: ${formatList(requiredPackages)}`,
+    ...installCommand ? [`- Install command: ${installCommand}`] : [],
+    ...verbose ? formatDoctorProjectTable(projects) : [],
     ...fixes.length > 0 ? ["", "Fixes applied:", ...fixes.map((fix) => `- ${fix}`)] : [],
     ...issues.length > 0 ? ["", "Issues:", ...issues.map((issue) => `- ${issue}`)] : [],
     ...warnings.length > 0 ? ["", "Warnings:", ...warnings.map((warning) => `- ${warning}`)] : []
@@ -715,6 +1208,15 @@ const applyDoctorFixes = (cwd, packageJson, configPath, configContent, summary)
       fixes.push(`Declared ${packageName}.`);
       packageChanged = true;
     }
+    const nodeEngine = assessConsumerNodeEngine(cwd, packageJson);
+    if (!nodeEngine.compatible && nodeEngine.targetRange) {
+      updated.engines ??= {};
+      updated.engines.node = nodeEngine.targetRange;
+      packageChanged = true;
+      fixes.push(
+        nodeEngine.consumerRange ? `Changed engines.node from ${nodeEngine.consumerRange} to ${nodeEngine.targetRange}.` : `Declared engines.node as ${nodeEngine.targetRange}.`
+      );
+    }
     if (packageChanged) {
       const packagePath = join(cwd, "package.json");
       const backupPath = createDoctorBackupPath(packagePath);
@@ -741,40 +1243,65 @@ const applyDoctorFixes = (cwd, packageJson, configPath, configContent, summary)
   return fixes;
 };
 const hasV1FrameworkPackageImports = (configContent) => configContent !== null && Object.keys(FRAMEWORK_PACKAGE_TO_KEY).some((packageName) => configContent.includes(packageName));
-const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = false, fix = false) => {
-  const packageManager = detectPackageManager(cwd);
-  const workspaceRoot = packageManager === "pnpm" && existsSync(join(cwd, "pnpm-workspace.yaml"));
-  let configPath = getConfigPathIfPresent(cwd);
-  let packageJson = readPackageJson(cwd);
+const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = false, fix = false, verbose = false) => {
+  const pnpmWorkspaceRoot = findPnpmWorkspaceRoot(cwd);
+  const projectRoot = pnpmWorkspaceRoot ?? cwd;
+  const packageManager = detectPackageManager(projectRoot);
+  const workspaceRoot = packageManager === "pnpm" && pnpmWorkspaceRoot !== void 0;
+  const catalog = workspaceRoot ? getCatalogPreference(readPackageJson(projectRoot)) : false;
+  let configPath = getConfigPathIfPresent(projectRoot);
+  let packageJson = readPackageJson(projectRoot);
   let declaredDependencies = getDeclaredDependencyNames(packageJson);
-  let summary = getInstallProjectSummary(cwd);
-  let activeConfig = await analyzeEslintConfig(cwd);
+  let summary = getInstallProjectSummary(projectRoot);
+  let activeConfig = await analyzeEslintConfig(projectRoot);
   let configContent = configPath ? readFileSync(configPath, "utf8") : null;
-  let liteInstallPackages = getLiteInstallPackages(summary, declaredDependencies);
-  let liteInstallCommand = createInstallCommand(packageManager, liteInstallPackages, workspaceRoot);
   let hasV1FrameworkImports = hasV1FrameworkPackageImports(configContent);
   if (liteInstall) {
+    const liteInstallPackages = getLiteInstallPackages(summary, declaredDependencies);
+    const liteInstallCommand = createInstallCommand(
+      packageManager,
+      addCompatibleConfigVersions(
+        liteInstallPackages,
+        getCompatibleConfigVersion(packageJson, getCliVersion(), pnpmWorkspaceRoot)
+      ),
+      workspaceRoot,
+      catalog
+    );
     if (json) {
-      console.log(JSON.stringify({ command: liteInstallCommand, packageManager, packages: liteInstallPackages }, null, 2));
+      console.log(JSON.stringify({
+        command: liteInstallCommand,
+        packageManager,
+        packages: liteInstallPackages
+      }, null, 2));
     } else {
       console.log(liteInstallCommand);
     }
     return;
   }
-  const fixes = fix ? applyDoctorFixes(cwd, packageJson, configPath, configContent, summary) : [];
+  const fixes = fix ? applyDoctorFixes(projectRoot, packageJson, configPath, configContent, summary) : [];
   if (fixes.length > 0) {
-    configPath = getConfigPathIfPresent(cwd);
-    packageJson = readPackageJson(cwd);
+    configPath = getConfigPathIfPresent(projectRoot);
+    packageJson = readPackageJson(projectRoot);
     declaredDependencies = getDeclaredDependencyNames(packageJson);
-    summary = getInstallProjectSummary(cwd);
-    activeConfig = await analyzeEslintConfig(cwd);
+    summary = getInstallProjectSummary(projectRoot);
+    activeConfig = await analyzeEslintConfig(projectRoot);
     configContent = configPath ? readFileSync(configPath, "utf8") : null;
-    liteInstallPackages = getLiteInstallPackages(summary, declaredDependencies);
-    liteInstallCommand = createInstallCommand(packageManager, liteInstallPackages, workspaceRoot);
     hasV1FrameworkImports = hasV1FrameworkPackageImports(configContent);
   }
+  const explicitFeaturePackages = configContent ? getExplicitConfigFeaturePackages(configContent) : [];
+  const requiredPackages = getInstallPackages(summary, declaredDependencies, explicitFeaturePackages);
+  const installCommand = requiredPackages.length > 0 ? createInstallCommand(
+    packageManager,
+    addCompatibleConfigVersions(
+      requiredPackages,
+      getCompatibleConfigVersion(packageJson, getCliVersion(), pnpmWorkspaceRoot)
+    ),
+    workspaceRoot,
+    catalog
+  ) : void 0;
   const { issues, warnings } = buildDoctorDiagnosis(
-    cwd,
+    projectRoot,
+    packageJson,
     configPath,
     configContent,
     hasV1FrameworkImports,
@@ -782,41 +1309,77 @@ const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = fal
     declaredDependencies,
     summary
   );
-  outputDoctorResult(json, configPath, packageManager, summary, liteInstallCommand, issues, warnings, fixes);
+  const projects = await getDoctorProjectActivations(projectRoot);
+  outputDoctorResult(
+    json,
+    verbose,
+    configPath,
+    packageManager,
+    summary,
+    installCommand,
+    requiredPackages,
+    issues,
+    warnings,
+    projects,
+    fixes
+  );
 };
-const handleInstall = (cwd = process.cwd(), dryRun = false) => {
-  const packageJson = readPackageJson(cwd);
+const isMinimumReleaseAgeFailure = (output) => /minimum[\s_-]*release[\s_-]*age/i.test(output) || /release (?:is )?(?:too young|not old enough)/i.test(output) || /blocked by (?:the )?minimum age/i.test(output);
+const handleInstall = (cwd = process.cwd(), dryRun = false, runner = spawnSync) => {
+  const pnpmWorkspaceRoot = findPnpmWorkspaceRoot(cwd);
+  const projectRoot = pnpmWorkspaceRoot ?? cwd;
+  const packageJson = readPackageJson(projectRoot);
   if (!packageJson) {
     console.error("\u274C package.json is missing or invalid.");
     process.exitCode = 1;
     return;
   }
-  const packageManager = detectPackageManager(cwd);
-  const configPath = getConfigPathIfPresent(cwd);
+  const packageManager = detectPackageManager(projectRoot);
+  const configPath = getConfigPathIfPresent(projectRoot);
   const explicitFeaturePackages = configPath ? getExplicitConfigFeaturePackages(readFileSync(configPath, "utf8")) : [];
   const packages = getInstallPackages(
-    getInstallProjectSummary(cwd),
+    getInstallProjectSummary(projectRoot),
     getDeclaredDependencyNames(packageJson),
     explicitFeaturePackages
   );
-  const workspaceRoot = packageManager === "pnpm" && existsSync(join(cwd, "pnpm-workspace.yaml"));
+  const workspaceRoot = packageManager === "pnpm" && pnpmWorkspaceRoot !== void 0;
+  const catalog = workspaceRoot ? getCatalogPreference(packageJson) : false;
+  const installPackages = addCompatibleConfigVersions(
+    packages,
+    getCompatibleConfigVersion(packageJson, getCliVersion(), pnpmWorkspaceRoot)
+  );
   if (packages.length === 0) {
     console.log("\u2705 All packages required by the detected ESLint configuration are already declared.");
     return;
   }
-  const installCommand = createInstallCommand(packageManager, packages, workspaceRoot);
+  const installCommand = createInstallCommand(packageManager, installPackages, workspaceRoot, catalog);
   if (dryRun) {
     console.log(installCommand);
     return;
   }
   console.log(`Installing detected ESLint dependencies:
 ${installCommand}`);
-  const [command, args] = createInstallInvocation(packageManager, packages, workspaceRoot);
-  const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+  const [command, args] = createInstallInvocation(packageManager, installPackages, workspaceRoot, catalog);
+  const result = runner(command, args, {
+    cwd: projectRoot,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: "pipe"
+  });
+  const stdout = String(result.stdout ?? "");
+  const stderr = String(result.stderr ?? "");
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
   if (result.error) {
     console.error(`\u274C Failed to run ${packageManager}: ${result.error.message}`);
     process.exitCode = 1;
   } else if (result.status !== 0) {
+    if (packageManager === "pnpm" && isMinimumReleaseAgeFailure(`${stdout}
+${stderr}`)) {
+      console.error(
+        `\u274C pnpm minimumReleaseAge temporarily blocks the compatible ESLint config release (${installPackages.join(", ")}). Keep the generated compatible range and either wait for the policy window or add the exact release to minimumReleaseAgeExclude in pnpm-workspace.yaml.`
+      );
+    }
     process.exitCode = result.status ?? 1;
   }
 };
@@ -943,7 +1506,7 @@ const dispatchCommand = (command, cwd, flags) => {
       break;
     }
     case "doctor": {
-      handleDoctor(cwd, flags.hasJson, flags.hasLiteInstall, flags.hasFix).catch((error) => {
+      handleDoctor(cwd, flags.hasJson, flags.hasLiteInstall, flags.hasFix, flags.hasVerbose).catch((error) => {
         console.error(`\u274C Failed to run doctor: ${String(error)}`);
         process.exitCode = 1;
       });
@@ -964,6 +1527,25 @@ const dispatchCommand = (command, cwd, flags) => {
       }
       break;
     }
+    case "explain-preset": {
+      if (!flags.positional) {
+        console.error("Missing preset. Usage: basic-eslint explain-preset <preset> [options]");
+        process.exitCode = 1;
+        break;
+      }
+      handleExplainPreset(cwd, flags.positional, {
+        analyzeSource: flags.hasAnalyzeSource,
+        compatibility: flags.hasCompatibility,
+        file: flags.files[0],
+        files: flags.files,
+        json: flags.hasJson,
+        output: flags.output
+      }).catch((error) => {
+        console.error(`\u274C Failed to explain preset: ${String(error)}`);
+        process.exitCode = 1;
+      });
+      break;
+    }
     case "generate-skill": {
       handleGenerateSkill(cwd, flags.hasForce, {
         check: flags.hasCheck,
@@ -1065,9 +1647,9 @@ const getNumericFlagValue = (argv, flag) => {
 };
 const runCli = (argv = process.argv, cwd = process.cwd()) => {
   const command = argv[2];
-  const isHelp = command === "--help" || command === "-h";
+  const isHelp = argv.slice(3).some((argument) => argument === "--help" || argument === "-h");
   const isVersion = command === "--version" || command === "-v";
-  if (!command || isHelp) {
+  if (!command || command === "--help" || command === "-h") {
     printUsage();
     return;
   }
@@ -1075,10 +1657,19 @@ const runCli = (argv = process.argv, cwd = process.cwd()) => {
     console.log(getCliVersion());
     return;
   }
+  if (isHelp) {
+    if (COMMAND_OPTIONS[command]) printCommandUsage(command);
+    else printUsage();
+    return;
+  }
+  const validation = validateCommandArguments(command, argv.slice(3));
+  if (!validation.ok) return;
   dispatchCommand(command, cwd, {
     concurrency: getFlagValue(argv, "--concurrency"),
     files: getFlagValues(argv, "--file"),
+    hasAnalyzeSource: argv.includes("--analyze-source"),
     hasCheck: argv.includes("--check"),
+    hasCompatibility: argv.includes("--compatibility"),
     hasCreate: argv.includes("--create"),
     hasDryRun: argv.includes("--dry-run"),
     hasExplicit: argv.includes("--explicit"),
@@ -1088,13 +1679,16 @@ const runCli = (argv = process.argv, cwd = process.cwd()) => {
     hasJson: argv.includes("--json"),
     hasLiteInstall: argv.includes("--lite-install"),
     hasPrune: argv.includes("--prune"),
+    hasVerbose: argv.includes("--verbose"),
     hasWithEslintMcp: argv.includes("--with-eslint-mcp"),
     hasWrite: argv.includes("--write"),
     maxDurationMs: getNumericFlagValue(argv, "--max-duration"),
     maxRuleTimeMs: getNumericFlagValue(argv, "--max-rule-time"),
     maxWarnings: getNumericFlagValue(argv, "--max-warnings"),
+    output: getFlagValue(argv, "--output"),
+    positional: validation.positional,
     preset: getFlagValue(argv, "--preset"),
-    rule: argv[3] && !argv[3].startsWith("-") ? argv[3] : void 0,
+    rule: command === "explain" ? validation.positional : void 0,
     snapshotPath: getFlagValue(argv, "--snapshot-path"),
     target: getFlagValue(argv, "--to")
   });
@@ -1114,3 +1708,4 @@ export {
   handleUpdate,
   runCli
 };
+//# sourceMappingURL=cli.js.map