@santi020k/eslint-config-basic 2.1.1 → 3.1.0

package/dist/cli.js

@@ -1,9 +1,22 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { analyzeEslintConfig, handleGenerateSkill } from "./agent-skill-generator.js";
+import {
+  analyzeEslintConfig,
+  ESLINT_CONFIG_FILENAMES,
+  handleGenerateSkill
+} from "./agent-skill-generator.js";
+import { handleCompatibility, handleExplainRule } from "./cli-advanced.js";
+import { getExplicitConfigFeaturePackages, handleMigrateV3 } from "./cli-migration.js";
+import {
+  handleBaseline,
+  handleProfile,
+  handleSnapshot,
+  handleSnapshotDiff
+} from "./cli-workflows.js";
 import { detectProjectOptions } from "./index.js";
 const getDefaultConfigFilename = (cwd) => {
   const packageJsonPath = join(cwd, "package.json");
@@ -16,15 +29,12 @@ const getDefaultConfigFilename = (cwd) => {
   }
 };
 const resolveConfigPath = (cwd) => {
-  const existingConfigPath = [
-    "eslint.config.js",
-    "eslint.config.mjs"
-  ].map((filename) => join(cwd, filename)).find((p) => existsSync(p));
+  const existingConfigPath = ESLINT_CONFIG_FILENAMES.map((filename) => join(cwd, filename)).find((p) => existsSync(p));
   return existingConfigPath ?? join(cwd, getDefaultConfigFilename(cwd));
 };
 const getFrameworkKeys = (detectedFrameworks) => {
   const frameworkKeys = new Set(detectedFrameworks ?? []);
-  if (frameworkKeys.has("next") || frameworkKeys.has("expo") || frameworkKeys.has("remix") || frameworkKeys.has("react-router") || frameworkKeys.has("tanstack-start") && !frameworkKeys.has("solid")) {
+  if (frameworkKeys.has("next") || frameworkKeys.has("expo") || frameworkKeys.has("react-router") || frameworkKeys.has("tanstack-start") && !frameworkKeys.has("solid")) {
     frameworkKeys.add("react");
   }
   return [...frameworkKeys].sort();
@@ -43,7 +53,7 @@ const FRAMEWORK_PACKAGE_TO_KEY = {
   "@santi020k/eslint-config-qwik": "qwik",
   "@santi020k/eslint-config-react": "react",
   "@santi020k/eslint-config-react-router": "react-router",
-  "@santi020k/eslint-config-remix": "remix",
+  "@santi020k/eslint-config-remix": "react-router",
   "@santi020k/eslint-config-slidev": "slidev",
   "@santi020k/eslint-config-solid": "solid",
   "@santi020k/eslint-config-svelte": "svelte",
@@ -51,18 +61,27 @@ const FRAMEWORK_PACKAGE_TO_KEY = {
   "@santi020k/eslint-config-vite": "vite",
   "@santi020k/eslint-config-vue": "vue"
 };
-const FRAMEWORK_KEY_TO_PACKAGE = Object.fromEntries(
-  Object.entries(FRAMEWORK_PACKAGE_TO_KEY).map(([packageName, framework]) => [framework, packageName])
-);
+const FRAMEWORK_KEY_TO_PACKAGE = {
+  ...Object.fromEntries(
+    Object.entries(FRAMEWORK_PACKAGE_TO_KEY).filter(([packageName]) => packageName !== "@santi020k/eslint-config-remix").map(([packageName, framework]) => [framework, packageName])
+  ),
+  "react-router": "@santi020k/eslint-config-react-router"
+};
 const LITE_PACKAGE_NAME = "@santi020k/eslint-config-lite";
 const INTEGRATIONS_PACKAGE_NAME = "@santi020k/eslint-config-integrations";
+const ASTRO_DOCTOR_PACKAGE_NAME = "@santi020k/eslint-plugin-astro-doctor";
+const BASIC_PACKAGE_NAME = "@santi020k/eslint-config-basic";
+const FULL_PACKAGE_NAME = "@santi020k/eslint-config-full";
 const TYPESCRIPT_PACKAGE_NAME = "typescript";
+const CATEGORY_PACKAGES = {
+  extensions: "@santi020k/eslint-config-extensions",
+  formats: "@santi020k/eslint-config-formats",
+  libraries: "@santi020k/eslint-config-libraries",
+  testing: "@santi020k/eslint-config-testing",
+  tools: "@santi020k/eslint-config-tools"
+};
 const getConfigPathIfPresent = (cwd) => {
-  const configPath = [
-    "eslint.config.js",
-    "eslint.config.mjs",
-    "eslint.config.cjs"
-  ].map((filename) => join(cwd, filename)).find((p) => existsSync(p));
+  const configPath = ESLINT_CONFIG_FILENAMES.map((filename) => join(cwd, filename)).find((p) => existsSync(p));
   return configPath ?? null;
 };
 const readPackageJson = (cwd) => {
@@ -112,7 +131,33 @@ const getLiteInstallPackages = (summary, declaredDependencies) => {
   }
   return [...packages];
 };
-const createInstallCommand = (packageManager, packages) => {
+const getInstallPackages = (summary, declaredDependencies, explicitFeaturePackages = []) => {
+  const usesFullPackage = declaredDependencies.has(FULL_PACKAGE_NAME);
+  const packages = /* @__PURE__ */ new Set(["eslint"]);
+  if (!usesFullPackage) packages.add(BASIC_PACKAGE_NAME);
+  if (!usesFullPackage) {
+    for (const framework of summary.frameworks) {
+      const packageName = FRAMEWORK_KEY_TO_PACKAGE[framework];
+      if (packageName) packages.add(packageName);
+    }
+    const categorySelections = [
+      [summary.extensions, CATEGORY_PACKAGES.extensions],
+      [summary.formats, CATEGORY_PACKAGES.formats],
+      [summary.libraries, CATEGORY_PACKAGES.libraries],
+      [summary.testing, CATEGORY_PACKAGES.testing],
+      [summary.tools, CATEGORY_PACKAGES.tools]
+    ];
+    for (const [features, packageName] of categorySelections) {
+      if (features.length > 0) packages.add(packageName);
+    }
+    for (const packageName of explicitFeaturePackages) {
+      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":
@@ -122,7 +167,19 @@ const createInstallCommand = (packageManager, packages) => {
     case "yarn":
       return `yarn add -D ${packageList}`;
     default:
-      return `pnpm add -D ${packageList}`;
+      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) => {
@@ -177,39 +234,40 @@ const detectWorkspaceProjects = (cwd) => {
   ];
   return [...new Set(patterns.flatMap((pattern) => expandWorkspacePattern(cwd, pattern)))].sort();
 };
-const getDetectionValues = (options) => ({
-  extensions: options.extensions ?? [],
-  formats: options.formats ?? [],
-  libraries: options.libraries ?? [],
-  runtime: options.runtime ?? "universal",
-  settings: options.settings ?? [],
-  testing: options.testing ?? [],
-  tools: options.tools ?? [],
-  typescript: options.typescript ?? false
-});
-const createConfigContent = (cwd) => {
-  const options = detectProjectOptions(cwd);
-  const values = getDetectionValues(options);
-  const frameworkKeys = getFrameworkKeys(options.detectedFrameworks);
-  const imports = ["import { eslintConfig } from '@santi020k/eslint-config-basic'"];
-  const presetLine = options.preset && options.preset !== "basic" ? `  preset: ${JSON.stringify(options.preset)},
-` : "";
-  const configContent = `${imports.join("\n")}
-
-export default await eslintConfig({
-${presetLine}  typescript: ${JSON.stringify(values.typescript)},
-  frameworks: {
-    ${frameworkKeys.map((key) => `${toPropertyKey(key)}: true`).join(",\n    ")}
-  },
-  libraries: ${JSON.stringify(values.libraries, null, 2)},
-  testing: ${JSON.stringify(values.testing, null, 2)},
-  formats: ${JSON.stringify(values.formats, null, 2)},
-  tools: ${JSON.stringify(values.tools, null, 2)},
-  extensions: ${JSON.stringify(values.extensions, null, 2)},
-  runtime: ${JSON.stringify(values.runtime)},
-  settings: ${JSON.stringify(values.settings, null, 2)}
-})
-`;
+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]
+  ];
+  if (summary.typescript) options.push("  typescript: true,");
+  if (summary.frameworks.length > 0) {
+    options.push(
+      "  frameworks: {",
+      ...summary.frameworks.map((framework) => `    ${toPropertyKey(framework)}: true,`),
+      "  },"
+    );
+  }
+  for (const [category, values] of optionalCategories) {
+    if (values.length > 0) {
+      options.push(`  ${category}: ${JSON.stringify(values)},`);
+    }
+  }
+  return options;
+};
+const createConfigContent = (cwd, explicit = false) => {
+  const explicitOptions = explicit ? createExplicitOptions(cwd) : [];
+  const invocation = explicitOptions.length > 0 ? ["export default defineConfig({", ...explicitOptions, "})"] : ["export default defineConfig()"];
+  const configContent = [
+    "import { defineConfig } from '@santi020k/eslint-config-basic'",
+    "",
+    ...invocation,
+    ""
+  ].join("\n");
   return {
     configContent,
     configPath: resolveConfigPath(cwd)
@@ -223,6 +281,7 @@ const getProjectSummary = (cwd) => {
   const options = detectProjectOptions(cwd);
   const workspaceProjects = detectWorkspaceProjects(cwd);
   return {
+    detectedProjects: Object.keys(options.projects ?? {}).sort(),
     extensions: options.extensions ?? [],
     formats: options.formats ?? [],
     frameworks: getFrameworkKeys(options.detectedFrameworks),
@@ -236,6 +295,30 @@ const getProjectSummary = (cwd) => {
     workspaceProjects
   };
 };
+const getInstallProjectSummary = (cwd) => {
+  const rootSummary = getProjectSummary(cwd);
+  const projectSummaries = rootSummary.detectedProjects.map((projectPath) => getProjectSummary(join(cwd, projectPath)));
+  const summaries = [rootSummary, ...projectSummaries];
+  return {
+    ...rootSummary,
+    extensions: [...new Set(summaries.flatMap((summary) => summary.extensions))],
+    formats: [...new Set(summaries.flatMap((summary) => summary.formats))],
+    frameworks: [...new Set(summaries.flatMap((summary) => summary.frameworks))].sort(),
+    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)
+  };
+};
+const getWorkspaceDeclaredConfigPackages = (cwd, summary) => {
+  const packages = /* @__PURE__ */ new Set();
+  for (const projectPath of summary.detectedProjects) {
+    for (const packageName of getDeclaredDependencyNames(readPackageJson(join(cwd, projectPath)))) {
+      if (packageName.startsWith("@santi020k/eslint-config-")) packages.add(packageName);
+    }
+  }
+  return [...packages];
+};
 const createStandardsContent = (cwd) => {
   const summary = getProjectSummary(cwd);
   return [
@@ -259,9 +342,9 @@ const createStandardsContent = (cwd) => {
     "## Recommended Config",
     "",
     "```js",
-    "import { eslintConfig } from '@santi020k/eslint-config-basic'",
+    "import { defineConfig } from '@santi020k/eslint-config-basic'",
     "",
-    "export default await eslintConfig()",
+    "export default await defineConfig()",
     "```",
     "",
     "Use `basic-eslint explain` when you want to inspect what the zero-config setup detects."
@@ -284,25 +367,45 @@ const printUsage = () => {
     "Commands:",
     "  init            Create eslint.config.js/mjs if missing",
     "  update          Regenerate eslint.config.js/mjs from detection",
-    "  explain         Print detected v2 config inputs",
+    "  explain         Print detected v3 config inputs",
     "  inspect         Print detected inputs and active config features",
-    "  doctor          Check project setup for common v2 adoption issues",
+    "  install         Install missing packages for detected v3 features",
+    "  doctor          Check project setup for common v3 adoption issues",
+    "  compatibility   Check runtime and config package compatibility",
     "  docs            Generate ESLINT_STANDARDS.md from detection",
-    "  migrate         Report v1-to-v2 migration suggestions",
+    "  migrate         Plan or apply v1-to-v2 and v2-to-v3 migrations",
+    "  baseline        Suppress existing violations for incremental adoption",
+    "  profile         Compare ESLint performance and report slow rules",
+    "  snapshot        Save the effective rules for representative files",
+    "  diff            Compare effective rules with the saved snapshot",
     "  generate-skill  Generate AI agent standards files",
     "",
     "Options:",
     "  --force         Overwrite existing generated skill sections/files",
-    "  --check         init: verify config exists; generate-skill: verify files are up to date",
+    "  --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)",
+    "  --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",
-    "  --lite-install  doctor: print the detected lite install command",
+    "  --lite-install  doctor: print the deprecated v2 Lite install command (removed in v4)",
+    "  --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",
+    "  --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)",
+    "  --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 handleInit = (cwd = process.cwd(), check = false) => {
+const handleInit = (cwd = process.cwd(), check = false, explicit = false) => {
   const configPath = resolveConfigPath(cwd);
   if (check) {
     const exists = existsSync(configPath);
@@ -319,7 +422,7 @@ const handleInit = (cwd = process.cwd(), check = false) => {
     return;
   }
   console.log("\u{1F50D} Detecting project settings...");
-  const { configContent } = createConfigContent(cwd);
+  const { configContent } = createConfigContent(cwd, explicit);
   writeFileSync(configPath, configContent);
   console.log(`\u2705 Created ${basename(configPath)} with auto-detected settings!`);
   console.log("\u{1F680} Ready to lint!");
@@ -386,6 +489,58 @@ const handleInspect = async (cwd = process.cwd(), json = false) => {
     `- Workspace projects: ${formatList(summary.workspaceProjects)}`
   ].join("\n"));
 };
+const semver = createRequire(import.meta.url)("semver");
+const readPackageMetadataFromMain = (mainPath, packageName) => {
+  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;
+    }
+    directory = dirname(directory);
+  }
+  return null;
+};
+const resolvePackageMetadata = (cwd, packageName) => {
+  try {
+    const projectRequire = createRequire(join(cwd, "package.json"));
+    try {
+      return readPackageMetadataFromMain(projectRequire.resolve(packageName), packageName);
+    } catch {
+      const integrationsMain = projectRequire.resolve(INTEGRATIONS_PACKAGE_NAME);
+      const integrationsRequire = createRequire(integrationsMain);
+      return readPackageMetadataFromMain(integrationsRequire.resolve(packageName), packageName);
+    }
+  } catch {
+    return null;
+  }
+};
+const getAstroDoctorNodeWarning = (metadata) => {
+  const nodeRange = metadata.engines?.node;
+  if (!nodeRange || semver.satisfies(process.versions.node, nodeRange)) return null;
+  return `Astro Doctor ${metadata.version ?? ""} requires Node ${nodeRange}, but the current runtime is ${process.versions.node}.`;
+};
+const getAstroDoctorEslintWarning = (metadata, eslintMetadata) => {
+  const eslintRange = metadata.peerDependencies?.eslint;
+  const eslintVersion = eslintMetadata?.version;
+  if (!eslintRange || !eslintVersion || semver.satisfies(eslintVersion, eslintRange)) return null;
+  return `Astro Doctor ${metadata.version ?? ""} requires ESLint ${eslintRange}, but this project resolves ${eslintVersion}.`;
+};
+const getAstroDoctorCompatibilityWarnings = (cwd, enabled) => {
+  if (!enabled) return [];
+  const pluginMetadata = resolvePackageMetadata(cwd, ASTRO_DOCTOR_PACKAGE_NAME);
+  if (!pluginMetadata) {
+    return [
+      `Astro Doctor is enabled, but ${ASTRO_DOCTOR_PACKAGE_NAME} could not be resolved. Reinstall dependencies or disable the \`astro-doctor\` feature.`
+    ];
+  }
+  const eslintMetadata = resolvePackageMetadata(cwd, "eslint");
+  return [
+    getAstroDoctorNodeWarning(pluginMetadata),
+    getAstroDoctorEslintWarning(pluginMetadata, eslintMetadata)
+  ].filter((warning) => warning !== null);
+};
 const findDuplicateEslint = (cwd = process.cwd()) => {
   try {
     const projectRequire = createRequire(join(cwd, "package.json"));
@@ -407,7 +562,9 @@ 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.");
   }
-  if (summary.workspaceProjects.length > 0 && !configContent.includes("projects:")) {
+  const usesBasicComposer = /from\s*['"]@santi020k\/eslint-config-(?:basic|full|lite)['"]/.test(configContent) && /\b(?:defineConfig|eslintConfig)\s*\(/.test(configContent);
+  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.");
   }
   if (configContent.includes(LITE_PACKAGE_NAME)) {
@@ -430,7 +587,7 @@ const validateConfigContent = (configContent, hasV1FrameworkImports, declaredDep
   }
   return warnings;
 };
-const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary) => {
+const validateProjectSetup = (cwd, configPath, activeConfig, hasV1FrameworkImports) => {
   const issues = [];
   const warnings = [];
   if (!readPackageJson(cwd)) {
@@ -444,18 +601,50 @@ const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImpo
   if (!hasLintScript(cwd)) {
     warnings.push("No `lint` script found in package.json.");
   }
-  if (configContent) {
-    warnings.push(...validateConfigContent(configContent, hasV1FrameworkImports, declaredDependencies, summary));
+  return { issues, warnings };
+};
+const isAstroDoctorConfigured = (activeConfig, configContent) => [
+  activeConfig?.extensions.includes("Astro Doctor") ?? false,
+  configContent?.includes("astro-doctor") ?? false,
+  configContent?.includes("AstroDoctor") ?? false
+].includes(true);
+const isAstroConfigured = (activeConfig, summary) => [
+  activeConfig?.frameworks.includes("Astro") ?? false,
+  summary.frameworks.includes("astro")
+].some(Boolean);
+const checkAstroDoctorStatus = (activeConfig, configContent, summary, warnings) => {
+  const astroDoctorEnabled = isAstroDoctorConfigured(activeConfig, configContent);
+  const astroEnabled = isAstroConfigured(activeConfig, summary);
+  if (astroDoctorEnabled && !astroEnabled) {
+    warnings.push(
+      "Astro Doctor is enabled without Astro. Enable `frameworks: { astro: true }` or remove the `astro-doctor` feature."
+    );
+  } else if (astroEnabled && !astroDoctorEnabled) {
+    warnings.push(
+      'Astro was detected without Astro Doctor. Enable `features: { "astro-doctor": true }` for additional Astro diagnostics.'
+    );
   }
+  return astroDoctorEnabled;
+};
+const checkDuplicateEslint = (cwd, warnings) => {
   const duplicateEslint = findDuplicateEslint(cwd);
   if (duplicateEslint) {
     warnings.push(
       `Two ESLint copies are installed: the project resolves ${duplicateEslint.projectVersion} while the config packages resolve ${duplicateEslint.configVersion}. Only ESLint 10 is supported, and parallel copies can apply different rule behavior between your editor and CLI. Align the project's eslint version with the config's (or dedupe via your package manager).`
     );
   }
+};
+const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary) => {
+  const { issues, warnings } = validateProjectSetup(cwd, configPath, activeConfig, hasV1FrameworkImports);
+  if (configContent) {
+    warnings.push(...validateConfigContent(configContent, hasV1FrameworkImports, declaredDependencies, summary));
+  }
+  const astroDoctorEnabled = checkAstroDoctorStatus(activeConfig, configContent, summary, warnings);
+  warnings.push(...getAstroDoctorCompatibilityWarnings(cwd, astroDoctorEnabled));
+  checkDuplicateEslint(cwd, warnings);
   return { issues, warnings };
 };
-const outputDoctorResult = (json, configPath, packageManager, summary, liteInstallCommand, issues, warnings) => {
+const outputDoctorResult = (json, configPath, packageManager, summary, liteInstallCommand, issues, warnings, fixes = []) => {
   let status = "passed";
   if (issues.length > 0) {
     status = "failed";
@@ -464,6 +653,7 @@ const outputDoctorResult = (json, configPath, packageManager, summary, liteInsta
   }
   const payload = {
     configFile: configPath ? basename(configPath) : null,
+    fixes,
     issues,
     liteInstallCommand,
     packageManager,
@@ -481,22 +671,88 @@ const outputDoctorResult = (json, configPath, packageManager, summary, liteInsta
     `- Package manager: ${payload.packageManager}`,
     `- Config file: ${payload.configFile ?? "none"}`,
     `- Workspace projects: ${formatList(summary.workspaceProjects)}`,
+    ...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}`)] : []
   ].join("\n"));
   if (issues.length > 0) process.exitCode = 1;
 };
-const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = false) => {
-  const configPath = getConfigPathIfPresent(cwd);
-  const packageJson = readPackageJson(cwd);
-  const declaredDependencies = getDeclaredDependencyNames(packageJson);
-  const summary = getProjectSummary(cwd);
-  const activeConfig = await analyzeEslintConfig(cwd);
-  const configContent = configPath ? readFileSync(configPath, "utf8") : null;
+const createDoctorBackupPath = (filePath) => {
+  const preferred = `${filePath}.doctor.bak`;
+  if (!existsSync(preferred)) return preferred;
+  let index = 2;
+  while (existsSync(`${preferred}.${index}`)) index++;
+  return `${preferred}.${index}`;
+};
+const getDoctorDependencyVersion = (packageName) => {
+  if (packageName === "eslint") return "^10.0.0";
+  if (packageName === TYPESCRIPT_PACKAGE_NAME) return "^5.0.0";
+  return "^3.0.0";
+};
+const applyDoctorFixes = (cwd, packageJson, configPath, configContent, summary) => {
+  const fixes = [];
+  if (packageJson) {
+    const updated = structuredClone(packageJson);
+    let packageChanged = false;
+    updated.scripts ??= {};
+    if (!updated.scripts.lint) {
+      updated.scripts.lint = "eslint .";
+      packageChanged = true;
+      fixes.push("Added the `lint` script.");
+    }
+    updated.devDependencies ??= {};
+    const declared = getDeclaredDependencyNames(packageJson);
+    const explicitFeaturePackages = configContent ? getExplicitConfigFeaturePackages(configContent) : [];
+    const missingPackages = getInstallPackages(summary, declared, explicitFeaturePackages);
+    const missingDependencies = Object.fromEntries(
+      missingPackages.map((packageName) => [packageName, getDoctorDependencyVersion(packageName)])
+    );
+    updated.devDependencies = {
+      ...updated.devDependencies,
+      ...missingDependencies
+    };
+    for (const packageName of missingPackages) {
+      fixes.push(`Declared ${packageName}.`);
+      packageChanged = true;
+    }
+    if (packageChanged) {
+      const packagePath = join(cwd, "package.json");
+      const backupPath = createDoctorBackupPath(packagePath);
+      writeFileSync(backupPath, `${JSON.stringify(packageJson, null, 2)}
+`);
+      writeFileSync(packagePath, `${JSON.stringify(updated, null, 2)}
+`);
+      fixes.push(`Backed up package.json to ${basename(backupPath)}.`);
+    }
+  }
+  if (!configPath) {
+    const generated = createConfigContent(cwd);
+    writeFileSync(generated.configPath, generated.configContent);
+    fixes.push(`Created ${basename(generated.configPath)}.`);
+  } else if (configContent && Object.keys(FRAMEWORK_PACKAGE_TO_KEY).some((packageName) => configContent.includes(packageName))) {
+    const result = migrateConfigContent(configContent);
+    if (result.changed) {
+      const backupPath = createDoctorBackupPath(configPath);
+      writeFileSync(backupPath, configContent);
+      writeFileSync(configPath, result.content);
+      fixes.push(`Migrated v1 framework imports and backed up the config to ${basename(backupPath)}.`);
+    }
+  }
+  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 liteInstallPackages = getLiteInstallPackages(summary, declaredDependencies);
-  const liteInstallCommand = createInstallCommand(packageManager, liteInstallPackages);
-  const hasV1FrameworkImports = configContent ? Object.keys(FRAMEWORK_PACKAGE_TO_KEY).some((packageName) => configContent.includes(packageName)) : false;
+  const workspaceRoot = packageManager === "pnpm" && existsSync(join(cwd, "pnpm-workspace.yaml"));
+  let configPath = getConfigPathIfPresent(cwd);
+  let packageJson = readPackageJson(cwd);
+  let declaredDependencies = getDeclaredDependencyNames(packageJson);
+  let summary = getInstallProjectSummary(cwd);
+  let activeConfig = await analyzeEslintConfig(cwd);
+  let configContent = configPath ? readFileSync(configPath, "utf8") : null;
+  let liteInstallPackages = getLiteInstallPackages(summary, declaredDependencies);
+  let liteInstallCommand = createInstallCommand(packageManager, liteInstallPackages, workspaceRoot);
+  let hasV1FrameworkImports = hasV1FrameworkPackageImports(configContent);
   if (liteInstall) {
     if (json) {
       console.log(JSON.stringify({ command: liteInstallCommand, packageManager, packages: liteInstallPackages }, null, 2));
@@ -505,8 +761,64 @@ const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = fal
     }
     return;
   }
-  const { issues, warnings } = buildDoctorDiagnosis(cwd, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary);
-  outputDoctorResult(json, configPath, packageManager, summary, liteInstallCommand, issues, warnings);
+  const fixes = fix ? applyDoctorFixes(cwd, packageJson, configPath, configContent, summary) : [];
+  if (fixes.length > 0) {
+    configPath = getConfigPathIfPresent(cwd);
+    packageJson = readPackageJson(cwd);
+    declaredDependencies = getDeclaredDependencyNames(packageJson);
+    summary = getInstallProjectSummary(cwd);
+    activeConfig = await analyzeEslintConfig(cwd);
+    configContent = configPath ? readFileSync(configPath, "utf8") : null;
+    liteInstallPackages = getLiteInstallPackages(summary, declaredDependencies);
+    liteInstallCommand = createInstallCommand(packageManager, liteInstallPackages, workspaceRoot);
+    hasV1FrameworkImports = hasV1FrameworkPackageImports(configContent);
+  }
+  const { issues, warnings } = buildDoctorDiagnosis(
+    cwd,
+    configPath,
+    configContent,
+    hasV1FrameworkImports,
+    activeConfig,
+    declaredDependencies,
+    summary
+  );
+  outputDoctorResult(json, configPath, packageManager, summary, liteInstallCommand, issues, warnings, fixes);
+};
+const handleInstall = (cwd = process.cwd(), dryRun = false) => {
+  const packageJson = readPackageJson(cwd);
+  if (!packageJson) {
+    console.error("\u274C package.json is missing or invalid.");
+    process.exitCode = 1;
+    return;
+  }
+  const packageManager = detectPackageManager(cwd);
+  const configPath = getConfigPathIfPresent(cwd);
+  const explicitFeaturePackages = configPath ? getExplicitConfigFeaturePackages(readFileSync(configPath, "utf8")) : [];
+  const packages = getInstallPackages(
+    getInstallProjectSummary(cwd),
+    getDeclaredDependencyNames(packageJson),
+    explicitFeaturePackages
+  );
+  const workspaceRoot = packageManager === "pnpm" && existsSync(join(cwd, "pnpm-workspace.yaml"));
+  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);
+  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" });
+  if (result.error) {
+    console.error(`\u274C Failed to run ${packageManager}: ${result.error.message}`);
+    process.exitCode = 1;
+  } else if (result.status !== 0) {
+    process.exitCode = result.status ?? 1;
+  }
 };
 const handleDocs = (cwd = process.cwd()) => {
   const outputPath = join(cwd, "ESLINT_STANDARDS.md");
@@ -520,9 +832,9 @@ const migrateConfigContent = (content) => {
   }
   const frameworks = getFrameworkKeys(importedFrameworks);
   const migrated = [
-    "import { eslintConfig } from '@santi020k/eslint-config-basic'",
+    "import { defineConfig } from '@santi020k/eslint-config-basic'",
     "",
-    "export default await eslintConfig({",
+    "export default await defineConfig({",
     "  frameworks: {",
     `    ${frameworks.map((key) => `${toPropertyKey(key)}: true`).join(",\n    ")}`,
     "  }",
@@ -547,7 +859,7 @@ const processConfigMigration = (configPath, write, suggestions) => {
     const backupPath = `${configPath}.bak`;
     writeFileSync(backupPath, configContent);
     writeFileSync(configPath, result.content);
-    const message = `Rewrote ${basename(configPath)} with v2 framework booleans: ${result.frameworks.join(", ")}. Original backed up to ${basename(backupPath)}.`;
+    const message = `Rewrote ${basename(configPath)} with framework booleans: ${result.frameworks.join(", ")}. Original backed up to ${basename(backupPath)}.`;
     applied.push(message);
     suggestions.push(`- ${message}`);
   } else {
@@ -555,15 +867,33 @@ const processConfigMigration = (configPath, write, suggestions) => {
   }
   return applied;
 };
-const handleMigrate = (cwd = process.cwd(), write = false, json = false) => {
+const handleMigrate = (cwd = process.cwd(), write = false, json = false, target = "v2", check = false, full = false) => {
+  if (target === "v3" || target === "3") {
+    const summary = getInstallProjectSummary(cwd);
+    handleMigrateV3(cwd, {
+      declaredConfigPackages: getWorkspaceDeclaredConfigPackages(cwd, summary),
+      extensions: summary.extensions,
+      formats: summary.formats,
+      frameworks: summary.frameworks,
+      libraries: summary.libraries,
+      packageManager: detectPackageManager(cwd),
+      testing: summary.testing,
+      tools: summary.tools,
+      typescript: summary.typescript
+    }, { check, full, json, write });
+    return;
+  }
+  if (target !== "v2" && target !== "2") {
+    throw new Error(`Unsupported migration target "${target}". Use --to v2 or --to v3.`);
+  }
   const configPath = getConfigPathIfPresent(cwd) ?? join(cwd, getDefaultConfigFilename(cwd));
   const suggestions = [
     "v1 to v2 migration suggestions:",
     "- Install only @santi020k/eslint-config-basic for the public config API.",
     "- Replace framework imports with bundled booleans such as frameworks: { react: true, next: true }.",
     "- Remove app-level @santi020k/eslint-config-react/next/vue/etc. config package imports.",
-    "- Try eslintConfig() first; v2 auto-detects supported frameworks and integrations.",
-    "- Use basic-eslint explain to review what v2 detects before committing the migration."
+    "- Try defineConfig() first; v3 auto-detects supported frameworks and integrations.",
+    "- Use basic-eslint explain to review what v3 detects before committing the migration."
   ];
   const applied = processConfigMigration(configPath, write, suggestions);
   if (json) {
@@ -580,30 +910,73 @@ const handleMigrate = (cwd = process.cwd(), write = false, json = false) => {
 };
 const dispatchCommand = (command, cwd, flags) => {
   switch (command) {
+    case "baseline": {
+      try {
+        handleBaseline(cwd, {
+          json: flags.hasJson,
+          preset: flags.preset,
+          prune: flags.hasPrune
+        });
+      } catch (error) {
+        console.error(`\u274C Failed to create ESLint baseline: ${String(error)}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "compatibility": {
+      handleCompatibility(cwd, flags.hasJson);
+      break;
+    }
+    case "diff": {
+      handleSnapshotDiff(cwd, {
+        files: flags.files,
+        json: flags.hasJson,
+        snapshotPath: flags.snapshotPath
+      }).catch((error) => {
+        console.error(`\u274C Failed to diff ESLint configuration: ${String(error)}`);
+        process.exitCode = 1;
+      });
+      break;
+    }
     case "docs": {
       handleDocs(cwd);
       break;
     }
     case "doctor": {
-      handleDoctor(cwd, flags.hasJson, flags.hasLiteInstall).catch((error) => {
+      handleDoctor(cwd, flags.hasJson, flags.hasLiteInstall, flags.hasFix).catch((error) => {
         console.error(`\u274C Failed to run doctor: ${String(error)}`);
         process.exitCode = 1;
       });
       break;
     }
     case "explain": {
-      handleExplain(cwd, flags.hasJson);
+      if (flags.rule) {
+        handleExplainRule(cwd, {
+          file: flags.files[0],
+          json: flags.hasJson,
+          rule: flags.rule
+        }).catch((error) => {
+          console.error(`\u274C Failed to explain ESLint rule: ${String(error)}`);
+          process.exitCode = 1;
+        });
+      } else {
+        handleExplain(cwd, flags.hasJson);
+      }
       break;
     }
     case "generate-skill": {
-      handleGenerateSkill(cwd, flags.hasForce, { check: flags.hasCheck, createAgentsMd: flags.hasCreate }).catch((error) => {
+      handleGenerateSkill(cwd, flags.hasForce, {
+        check: flags.hasCheck,
+        createAgentsMd: flags.hasCreate,
+        withEslintMcp: flags.hasWithEslintMcp
+      }).catch((error) => {
         console.error(`\u274C Failed to generate skill files: ${String(error)}`);
         process.exitCode = 1;
       });
       break;
     }
     case "init": {
-      handleInit(cwd, flags.hasCheck);
+      handleInit(cwd, flags.hasCheck, flags.hasExplicit);
       break;
     }
     case "inspect": {
@@ -613,8 +986,52 @@ const dispatchCommand = (command, cwd, flags) => {
       });
       break;
     }
+    case "install": {
+      handleInstall(cwd, flags.hasDryRun);
+      break;
+    }
     case "migrate": {
-      handleMigrate(cwd, flags.hasWrite, flags.hasJson);
+      try {
+        handleMigrate(
+          cwd,
+          flags.hasWrite,
+          flags.hasJson,
+          flags.target ?? "v2",
+          flags.hasCheck,
+          flags.hasFull
+        );
+      } catch (error) {
+        console.error(`\u274C Failed to migrate ESLint configuration: ${String(error)}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "profile": {
+      try {
+        handleProfile(cwd, {
+          concurrency: flags.concurrency,
+          files: flags.files,
+          json: flags.hasJson,
+          maxDurationMs: flags.maxDurationMs,
+          maxRuleTimeMs: flags.maxRuleTimeMs,
+          maxWarnings: flags.maxWarnings
+        });
+      } catch (error) {
+        console.error(`\u274C Failed to profile ESLint: ${String(error)}`);
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "snapshot": {
+      handleSnapshot(cwd, {
+        check: flags.hasCheck,
+        files: flags.files,
+        json: flags.hasJson,
+        snapshotPath: flags.snapshotPath
+      }).catch((error) => {
+        console.error(`\u274C Failed to snapshot ESLint configuration: ${String(error)}`);
+        process.exitCode = 1;
+      });
       break;
     }
     case "update": {
@@ -628,6 +1045,24 @@ const dispatchCommand = (command, cwd, flags) => {
     }
   }
 };
+const getFlagValue = (argv, flag) => {
+  const inline = argv.find((argument) => argument.startsWith(`${flag}=`));
+  if (inline) return inline.slice(flag.length + 1);
+  const index = argv.indexOf(flag);
+  return index >= 0 ? argv[index + 1] : void 0;
+};
+const getFlagValues = (argv, flag) => argv.flatMap((argument, index) => {
+  if (argument.startsWith(`${flag}=`)) return [argument.slice(flag.length + 1)];
+  if (argument === flag && argv[index + 1]) return [argv[index + 1]];
+  return [];
+});
+const getNumericFlagValue = (argv, flag) => {
+  const value = getFlagValue(argv, flag);
+  const present = argv.includes(flag) || argv.some((argument) => argument.startsWith(`${flag}=`));
+  if (!present) return void 0;
+  if (value === void 0 || value.trim() === "" || value.startsWith("--")) return Number.NaN;
+  return Number(value);
+};
 const runCli = (argv = process.argv, cwd = process.cwd()) => {
   const command = argv[2];
   const isHelp = command === "--help" || command === "-h";
@@ -641,12 +1076,27 @@ const runCli = (argv = process.argv, cwd = process.cwd()) => {
     return;
   }
   dispatchCommand(command, cwd, {
+    concurrency: getFlagValue(argv, "--concurrency"),
+    files: getFlagValues(argv, "--file"),
     hasCheck: argv.includes("--check"),
     hasCreate: argv.includes("--create"),
+    hasDryRun: argv.includes("--dry-run"),
+    hasExplicit: argv.includes("--explicit"),
+    hasFix: argv.includes("--fix"),
     hasForce: argv.includes("--force"),
+    hasFull: argv.includes("--full"),
     hasJson: argv.includes("--json"),
     hasLiteInstall: argv.includes("--lite-install"),
-    hasWrite: argv.includes("--write")
+    hasPrune: argv.includes("--prune"),
+    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"),
+    preset: getFlagValue(argv, "--preset"),
+    rule: argv[3] && !argv[3].startsWith("-") ? argv[3] : void 0,
+    snapshotPath: getFlagValue(argv, "--snapshot-path"),
+    target: getFlagValue(argv, "--to")
   });
 };
 if (process.argv[1] && (process.argv[1] === fileURLToPath(import.meta.url) || process.argv[1].endsWith("cli.js") || process.argv[1].endsWith("cli.ts"))) {
@@ -659,6 +1109,7 @@ export {
   handleExplain,
   handleInit,
   handleInspect,
+  handleInstall,
   handleMigrate,
   handleUpdate,
   runCli