@santi020k/eslint-config-basic 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @santi020k/eslint-config-basic
 
+## 3.1.0
+
+### Minor Changes
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Add an opt-in, lazily loaded Astro Doctor ESLint integration through `Extension.AstroDoctor` or `features: { "astro-doctor": true }`, including the recommended proprietary and official Astro rules, configuration validation, and `basic-eslint doctor` compatibility guidance.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Add a `basic-eslint install` command that detects missing framework, feature
+  category, ESLint, and TypeScript dependencies and installs them with the
+  project's package manager. Document the command in the v3 setup flow.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Complete the v3 lean dependency boundary and one-line recommended entry point. Framework and feature-pack packages are now optional, dynamically loaded peers with actionable installation errors. Feature factories move from the basic root export to granular extensions, formats, libraries, testing, and tools packages; `@santi020k/eslint-config-integrations` remains as a compatibility aggregate, while the new `@santi020k/eslint-config-full` package provides the batteries-included installation path. Core no longer owns JSX accessibility rules, the CLI writes the one-line configuration, and release checks enforce dependency budgets, packed-consumer compatibility, and lean production-audit boundaries.
+
+  Remove the v1 compatibility exports (`*Config`, `jsConfig`, `tsConfig`,
+  `astroConfig`, `rules`, `loadModule`, and `eslintConfig`) from the aggregate
+  v3 API. Remove the deprecated Remix package and `frameworks.remix` option;
+  Remix dependencies now resolve through the React Router v7 configuration.
+  The Lite package is now a thin compatibility re-export of Basic.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Complete the v3 modular dependency boundary with five category feature packs.
+  Each pack owns its plugin dependencies and exposes a self-describing feature
+  registry through the shared `ConfigFeature` contract. The lean Basic composer
+  loads only registries for selected categories, Full installs every pack, and
+  Integrations remains as a compatibility aggregate.
+
+  Move agent-skill generation from the Basic root export to
+  `@santi020k/eslint-config-basic/agent`, keeping Node-oriented tooling out of the
+  configuration runtime entry point.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Polish real-world consumer configuration: add one `root` option for detection,
+  TypeScript, Tailwind, projects, and `.gitignore`; auto-detect and scope workspace
+  packages without leaking root framework dependencies; accept native project
+  service options; and syntax-lint TypeScript config files plus explicit
+  `untypedFiles` without consumer-side `typescript-eslint` imports.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Drop Node.js 20 support and require Node.js 22.19.0 or newer across the package
+  suite. This aligns the published engine contract with the current ESLint,
+  Lighthouse, GraphQL, and Unicorn toolchain.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Add v3 lifecycle tooling to the `basic-eslint` CLI: an automated v2-to-v3
+  migration planner and writer, incremental strict-mode baselines backed by ESLint
+  bulk suppressions, rule-performance profiling with concurrency comparison,
+  effective-rule snapshots and diffs, and optional official ESLint MCP
+  scaffolding for generated agent standards.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Add v3 project-assistance workflows: safe doctor repairs, explicit init output,
+  effective rule/source explanations, package compatibility reporting, lint
+  warning and performance budgets, real v2 migration fixtures, and a reusable
+  GitHub Action for consumer checks.
+
+### Patch Changes
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Resolve package-scoped Tailwind and Astro configuration roots, keep lazy framework imports anchored to their declaring package, add shared `projectDefaults` inheritance for monorepos, and move integration host libraries to optional peers.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Deprecate the Lite and Integrations compatibility packages during v3 and
+  schedule their removal for v4. Add TypeScript deprecation annotations,
+  migration guidance, and post-publish npm registry warnings. Also deprecate the
+  `integrations` option alias and `doctor --lite-install` compatibility workflow.
+
+- [#99](https://github.com/santi020k/eslint-config-basic/pull/99) [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967) Thanks [@santi020k](https://github.com/santi020k)! - Include explicit feature, preset, and strict config selections in CLI install
+  and doctor repair planning, preserve runtime dependency fields and peer metadata
+  during v3 migrations, analyze TypeScript ESLint config files during doctor
+  checks, and honor dot-prefixed workspace exclusion patterns during project
+  detection.
+- Updated dependencies [[`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967), [`0f89b89`](https://github.com/santi020k/eslint-config-basic/commit/0f89b89b466732ea582650b4e0baee0c47b0c967)]:
+  - @santi020k/eslint-config-core@3.1.0
+  - @santi020k/eslint-config-typescript@3.1.0
+
 ## 3.0.0
 
 ### Major Changes

package/README.md

@@ -1,19 +1,11 @@
 # @santi020k/eslint-config-basic
 
-The lean v3 default for ESLint 10 flat config.
+The primary entry point that composes all feature-specific configurations.
 
-```sh
-npm install -D eslint @santi020k/eslint-config-basic
-```
+This package is part of the [`@santi020k/eslint-config-basic`](https://github.com/santi020k/eslint-config-basic) monorepo.
 
-```js
-export { default } from '@santi020k/eslint-config-basic/recommended'
-```
+- Docs: [Main package](https://eslint.santi020k.com/packages/basic)
+- Repository: [santi020k/eslint-config-basic](https://github.com/santi020k/eslint-config-basic)
+- Author: [santi020k](https://santi020k.com)
 
-Add only the framework packages and `@santi020k/eslint-config-integrations`
-that the project uses. Choose `@santi020k/eslint-config-full` for the
-batteries-included dependency model.
-
-- [Documentation](https://eslint.santi020k.com/)
-- [Migration from v2](https://eslint.santi020k.com/guide/migration-v2-to-v3/)
-- [Repository](https://github.com/santi020k/eslint-config-basic)
+The canonical documentation lives on the Starlight site, so this README intentionally stays short to avoid duplication.

package/dist/agent-skill-generator.d.ts

@@ -1,3 +1,4 @@
+declare const ESLINT_CONFIG_FILENAMES: readonly ["eslint.config.js", "eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts", "eslint.config.mts", "eslint.config.cts"];
 interface AgentTarget {
     /** Format variant used when generating content */
     format: 'cursor' | 'frontmatter' | 'kiro' | 'plain';
@@ -50,6 +51,12 @@ interface GenerateSkillOptions {
      * @default false
      */
     force?: boolean;
+    /**
+     * Add the official `eslint --mcp` server to the project root `.mcp.json`.
+     * Existing unrelated MCP server entries are preserved.
+     * @default false
+     */
+    withEslintMcp?: boolean;
 }
 interface GenerateSkillResult {
     skipped: string[];
@@ -90,7 +97,7 @@ declare const generateSkillContent: (features: EslintConfigFeatures, format: Age
  *
  * @example
  * ```ts
- * import { generateAgentSkills } from '@santi020k/eslint-config-basic'
+ * import { generateAgentSkills } from '@santi020k/eslint-config-basic/agent'
  *
  * const result = await generateAgentSkills({ cwd: process.cwd() })
  * process.stdout.write(`Written to: ${result.written}\n`)
@@ -102,7 +109,9 @@ interface HandleGenerateSkillFlags {
     check?: boolean;
     /** Create a root `AGENTS.md` when it does not exist */
     createAgentsMd?: boolean;
+    /** Add the official ESLint MCP server to `.mcp.json` */
+    withEslintMcp?: boolean;
 }
 declare const handleGenerateSkill: (cwd?: string, force?: boolean, flags?: HandleGenerateSkillFlags) => Promise<void>;
 
-export { AGENT_TARGETS, type AgentTarget, type EslintConfigFeatures, type GenerateSkillOptions, type GenerateSkillResult, type HandleGenerateSkillFlags, analyzeEslintConfig, generateAgentSkills, generateSkillContent, handleGenerateSkill };
+export { AGENT_TARGETS, type AgentTarget, ESLINT_CONFIG_FILENAMES, type EslintConfigFeatures, type GenerateSkillOptions, type GenerateSkillResult, type HandleGenerateSkillFlags, analyzeEslintConfig, generateAgentSkills, generateSkillContent, handleGenerateSkill };

package/dist/agent-skill-generator.js

@@ -2,6 +2,14 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { detectProjectOptions } from "./index.js";
+const ESLINT_CONFIG_FILENAMES = [
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs",
+  "eslint.config.ts",
+  "eslint.config.mts",
+  "eslint.config.cts"
+];
 const AGENT_TARGETS = [
   {
     format: "frontmatter",
@@ -97,7 +105,6 @@ const FEATURE_MAP = [
   ["eslint-config-expo/", "frameworks", "Expo"],
   ["eslint-config-qwik/", "frameworks", "Qwik"],
   ["eslint-config-react-router/", "frameworks", "React Router"],
-  ["eslint-config-remix/", "frameworks", "Remix"],
   ["eslint-config-solid/", "frameworks", "SolidJS"],
   ["eslint-config-nuxt/", "frameworks", "Nuxt"],
   ["eslint-config-lit/", "frameworks", "Lit"],
@@ -187,7 +194,6 @@ const DETECTED_FRAMEWORK_LABELS = /* @__PURE__ */ new Map([
   ["qwik", "Qwik"],
   ["react", "React"],
   ["react-router", "React Router"],
-  ["remix", "Remix"],
   ["slidev", "Slidev"],
   ["solid", "SolidJS"],
   ["svelte", "Svelte"],
@@ -302,7 +308,7 @@ const extractFeatures = (configs, lintCommand, configFile) => {
   return features;
 };
 const findEslintConfig = (cwd) => {
-  for (const name of ["eslint.config.js", "eslint.config.mjs", "eslint.config.cjs"]) {
+  for (const name of ESLINT_CONFIG_FILENAMES) {
     const p = join(cwd, name);
     if (existsSync(p)) return p;
   }
@@ -594,10 +600,46 @@ const resolveSkillOptions = (opts) => ({
   check: opts.check ?? false,
   createAgentsMd: opts.createAgentsMd ?? false,
   cwd: opts.cwd ?? process.cwd(),
-  force: opts.force ?? false
+  force: opts.force ?? false,
+  withEslintMcp: opts.withEslintMcp ?? false
 });
+const createEslintMcpServer = (cwd) => {
+  if (existsSync(join(cwd, "pnpm-lock.yaml")) || existsSync(join(cwd, "pnpm-workspace.yaml"))) {
+    return { args: ["exec", "eslint", "--mcp"], command: "pnpm" };
+  }
+  if (existsSync(join(cwd, "yarn.lock"))) {
+    return { args: ["exec", "eslint", "--mcp"], command: "yarn" };
+  }
+  if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock"))) {
+    return { args: ["eslint", "--mcp"], command: "bunx" };
+  }
+  return { args: ["eslint", "--mcp"], command: "npx" };
+};
+const handleEslintMcpConfig = (cwd, force, check) => {
+  const configPath = join(cwd, ".mcp.json");
+  const server = createEslintMcpServer(cwd);
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      throw new Error(".mcp.json is invalid JSON; fix it before adding the ESLint MCP server.");
+    }
+  }
+  const current = config.mcpServers?.eslint;
+  const isCurrent = JSON.stringify(current) === JSON.stringify(server);
+  if (check) return isCurrent ? "skipped" : "stale";
+  if (current && !force) return "skipped";
+  config.mcpServers = {
+    ...config.mcpServers,
+    eslint: server
+  };
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+`);
+  return "written";
+};
 const generateAgentSkills = async (opts = {}) => {
-  const { check, createAgentsMd, cwd, force } = resolveSkillOptions(opts);
+  const { check, createAgentsMd, cwd, force, withEslintMcp } = resolveSkillOptions(opts);
   const written = [];
   const skipped = [];
   const stale = [];
@@ -620,6 +662,10 @@ const generateAgentSkills = async (opts = {}) => {
   recordGuardedResult(copilotPath, handleGuardedSectionFile(copilotPath, plainBody, force, check));
   const agentsMdPath = join(cwd, AGENTS_MD_PATH);
   recordGuardedResult(agentsMdPath, handleGuardedSectionFile(agentsMdPath, plainBody, force, check, createAgentsMd));
+  if (withEslintMcp) {
+    const eslintMcpPath = join(cwd, ".mcp.json");
+    recordGuardedResult(eslintMcpPath, handleEslintMcpConfig(cwd, force, check));
+  }
   for (const target of AGENT_TARGETS) {
     const agentFolder = join(cwd, target.markerFolder);
     if (!existsSync(agentFolder)) continue;
@@ -640,7 +686,8 @@ const generateAgentSkills = async (opts = {}) => {
 };
 const resolveGenerateSkillFlags = (flags) => ({
   check: flags.check ?? false,
-  createAgentsMd: flags.createAgentsMd ?? false
+  createAgentsMd: flags.createAgentsMd ?? false,
+  withEslintMcp: flags.withEslintMcp ?? false
 });
 const outputGenerateSkillResults = (check, result, cwd) => {
   if (check) {
@@ -675,7 +722,7 @@ const outputGenerateSkillResults = (check, result, cwd) => {
   }
 };
 const handleGenerateSkill = async (cwd = process.cwd(), force = false, flags = {}) => {
-  const { check, createAgentsMd } = resolveGenerateSkillFlags(flags);
+  const { check, createAgentsMd, withEslintMcp } = resolveGenerateSkillFlags(flags);
   console.log(check ? "\u{1F50D} Checking AI agent skill files..." : "\u{1F50D} Scanning for AI agent folders...");
   const configFile = findEslintConfig(cwd);
   if (configFile) {
@@ -683,7 +730,7 @@ const handleGenerateSkill = async (cwd = process.cwd(), force = false, flags = {
   } else {
     console.log("\u26A0\uFE0F  No eslint.config.js found \u2014 falling back to package.json detection.");
   }
-  const result = await generateAgentSkills({ check, createAgentsMd, cwd, force });
+  const result = await generateAgentSkills({ check, createAgentsMd, cwd, force, withEslintMcp });
   if (result.written.length === 0 && result.skipped.length === 0 && result.stale.length === 0) {
     console.log("\n\u26A0\uFE0F  No agent folders found (.agent, .agents, .claude, .cursor, .windsurf, .copilot, .aider, .gemini, .clinerules, .roo, .kiro) and no AGENTS.md.");
     console.log("   Create one of those folders first (or re-run with --create to scaffold AGENTS.md).");
@@ -693,6 +740,7 @@ const handleGenerateSkill = async (cwd = process.cwd(), force = false, flags = {
 };
 export {
   AGENT_TARGETS,
+  ESLINT_CONFIG_FILENAMES,
   analyzeEslintConfig,
   generateAgentSkills,
   generateSkillContent,

package/dist/cli-advanced.d.ts

@@ -0,0 +1,23 @@
+interface ExplainRuleOptions {
+    file?: string;
+    json?: boolean;
+    rule: string;
+}
+declare const handleExplainRule: (cwd: string | undefined, options: ExplainRuleOptions) => Promise<void>;
+declare const createCompatibilityReport: (cwd?: string) => {
+    compatible: boolean;
+    packages: {
+        declared: string;
+        issues: string[];
+        name: string;
+        resolved: string | null;
+    }[];
+    runtime: {
+        eslint: string | null;
+        node: string;
+        typescript: string | null;
+    };
+};
+declare const handleCompatibility: (cwd?: string, json?: boolean) => void;
+
+export { type ExplainRuleOptions, createCompatibilityReport, handleCompatibility, handleExplainRule };

package/dist/cli-advanced.js

@@ -0,0 +1,217 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+const CONFIG_FILENAMES = [
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs",
+  "eslint.config.ts",
+  "eslint.config.mts",
+  "eslint.config.cts"
+];
+const RULE_PACKAGE_HINTS = {
+  "@angular-eslint": "@santi020k/eslint-config-angular",
+  "@eslint-react": "@santi020k/eslint-config-react",
+  "@next/next": "@santi020k/eslint-config-next",
+  "@typescript-eslint": "@santi020k/eslint-config-typescript",
+  astro: "@santi020k/eslint-config-astro",
+  cypress: "@santi020k/eslint-config-testing",
+  jest: "@santi020k/eslint-config-testing",
+  "jsonc": "@santi020k/eslint-config-formats",
+  playwright: "@santi020k/eslint-config-testing",
+  react: "@santi020k/eslint-config-react",
+  "testing-library": "@santi020k/eslint-config-testing",
+  unicorn: "@santi020k/eslint-config-extensions",
+  vue: "@santi020k/eslint-config-vue"
+};
+const semver = createRequire(import.meta.url)("semver");
+const readJson = (filePath) => {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+};
+const findConfigPath = (cwd) => CONFIG_FILENAMES.map((file) => join(cwd, file)).find((file) => existsSync(file)) ?? null;
+const flattenConfig = async (value) => {
+  const resolved = await value;
+  if (Array.isArray(resolved)) {
+    const nested = await Promise.all(resolved.map((entry) => flattenConfig(entry)));
+    return nested.flat();
+  }
+  if (resolved && typeof resolved === "object") return [resolved];
+  return [];
+};
+const loadConfigEntries = async (configPath) => {
+  if (!configPath) return [];
+  try {
+    const loaded = await import(`${pathToFileURL(configPath).href}?basic-eslint-explain=${Date.now()}`);
+    if (!loaded || typeof loaded !== "object" || !("default" in loaded)) return [];
+    return await flattenConfig(loaded.default);
+  } catch {
+    return [];
+  }
+};
+const loadProjectEslint = (cwd) => {
+  const projectRequire = createRequire(join(cwd, "package.json"));
+  const eslintModule = projectRequire("eslint");
+  if (!eslintModule.ESLint) throw new Error("The installed eslint package does not expose the ESLint API.");
+  return new eslintModule.ESLint({ cwd });
+};
+const getRuleSeverity = (ruleValue) => Array.isArray(ruleValue) ? ruleValue[0] : ruleValue;
+const isRuleEnabled = (ruleValue) => {
+  const severity = getRuleSeverity(ruleValue);
+  return severity !== 0 && severity !== "off";
+};
+const getPackageHint = (rule) => {
+  const prefix = rule.includes("/") ? rule.slice(0, rule.indexOf("/")) : rule;
+  const scopedPrefix = rule.startsWith("@") ? rule.split("/").slice(0, 2).join("/") : prefix;
+  return RULE_PACKAGE_HINTS[scopedPrefix] ?? RULE_PACKAGE_HINTS[prefix] ?? null;
+};
+const handleExplainRule = async (cwd = process.cwd(), options) => {
+  const configPath = findConfigPath(cwd);
+  const file = options.file ?? "eslint.config.js";
+  const eslint = loadProjectEslint(cwd);
+  const effective = await eslint.calculateConfigForFile(file);
+  const effectiveValue = effective?.rules?.[options.rule];
+  const entries = await loadConfigEntries(configPath);
+  const sources = entries.flatMap((entry, index) => {
+    if (!entry.rules || !Object.hasOwn(entry.rules, options.rule)) return [];
+    return [{
+      files: entry.files ?? null,
+      index,
+      name: entry.name ?? `anonymous config #${index + 1}`,
+      value: entry.rules[options.rule]
+    }];
+  });
+  const payload = {
+    configFile: configPath ? basename(configPath) : null,
+    effective: effectiveValue ?? null,
+    enabled: effectiveValue !== void 0 && isRuleEnabled(effectiveValue),
+    file,
+    packageHint: getPackageHint(options.rule),
+    rule: options.rule,
+    severity: effectiveValue === void 0 ? null : getRuleSeverity(effectiveValue),
+    sources
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log([
+      `ESLint rule explanation: ${payload.rule}`,
+      `- File: ${payload.file}`,
+      `- Config: ${payload.configFile ?? "none"}`,
+      `- Effective value: ${JSON.stringify(payload.effective)}`,
+      `- Enabled: ${payload.enabled ? "yes" : "no"}`,
+      `- Likely package: ${payload.packageHint ?? "core or custom config"}`,
+      `- Defining entries: ${payload.sources.length}`
+    ].join("\n"));
+    for (const source of payload.sources) {
+      console.log(`  - ${source.name}: ${JSON.stringify(source.value)}`);
+    }
+  }
+  if (effectiveValue === void 0) process.exitCode = 1;
+};
+const getDependencyVersions = (manifest) => {
+  const fields = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+  const dependencies = {};
+  for (const field of fields) {
+    const values = manifest?.[field];
+    if (!values || typeof values !== "object" || Array.isArray(values)) continue;
+    for (const [name, version] of Object.entries(values)) {
+      if (typeof version === "string") dependencies[name] = version;
+    }
+  }
+  return dependencies;
+};
+const readResolvedManifest = (projectRequire, packageName) => {
+  try {
+    let directory = dirname(projectRequire.resolve(packageName));
+    for (let depth = 0; depth < 6; depth++) {
+      const manifestPath = join(directory, "package.json");
+      const manifest = readJson(manifestPath);
+      if (manifest?.name === packageName) return manifest;
+      directory = dirname(directory);
+    }
+  } catch {
+    return null;
+  }
+  return null;
+};
+const readWorkspaceManifest = (cwd, packageName) => {
+  const packagesPath = join(cwd, "packages");
+  if (!existsSync(packagesPath)) return null;
+  for (const entry of readdirSync(packagesPath, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const manifest = readJson(join(packagesPath, entry.name, "package.json"));
+    if (manifest?.name === packageName) return manifest;
+  }
+  return null;
+};
+const createCompatibilityReport = (cwd = process.cwd()) => {
+  const rootManifest = readJson(join(cwd, "package.json"));
+  const declared = getDependencyVersions(rootManifest);
+  const projectRequire = createRequire(join(cwd, "package.json"));
+  const configPackages = Object.keys(declared).filter((name) => name.startsWith("@santi020k/eslint-config-")).sort();
+  const runtimeVersions = {
+    eslint: readResolvedManifest(projectRequire, "eslint")?.version ?? null,
+    node: process.versions.node,
+    typescript: readResolvedManifest(projectRequire, "typescript")?.version ?? null
+  };
+  const packages = configPackages.map((name) => {
+    const manifest = readResolvedManifest(projectRequire, name) ?? readWorkspaceManifest(cwd, name);
+    const issues = [];
+    if (!manifest) {
+      issues.push("declared but not installed");
+    } else {
+      const nodeRange = manifest.engines?.node;
+      if (nodeRange && !semver.satisfies(runtimeVersions.node, nodeRange)) {
+        issues.push(`requires Node ${nodeRange}`);
+      }
+      for (const peer of ["eslint", "typescript"]) {
+        const range = manifest.peerDependencies?.[peer];
+        const version = runtimeVersions[peer];
+        if (range && version && !semver.satisfies(version, range)) {
+          issues.push(`requires ${peer} ${range}, resolved ${version}`);
+        }
+      }
+    }
+    return {
+      declared: declared[name],
+      issues,
+      name,
+      resolved: manifest?.version ?? null
+    };
+  });
+  return {
+    compatible: packages.every((item) => item.issues.length === 0),
+    packages,
+    runtime: runtimeVersions
+  };
+};
+const handleCompatibility = (cwd = process.cwd(), json = false) => {
+  const report = createCompatibilityReport(cwd);
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log([
+      `ESLint compatibility: ${report.compatible ? "compatible" : "issues found"}`,
+      `- Node: ${report.runtime.node}`,
+      `- ESLint: ${report.runtime.eslint ?? "not installed"}`,
+      `- TypeScript: ${report.runtime.typescript ?? "not installed"}`
+    ].join("\n"));
+    for (const item of report.packages) {
+      console.log(
+        `- ${item.name}: ${item.resolved ?? "not installed"}` + (item.issues.length > 0 ? ` (${item.issues.join("; ")})` : "")
+      );
+    }
+  }
+  if (!report.compatible) process.exitCode = 1;
+};
+export {
+  createCompatibilityReport,
+  handleCompatibility,
+  handleExplainRule
+};

package/dist/cli-migration.d.ts

@@ -0,0 +1,26 @@
+interface V3MigrationContext {
+    declaredConfigPackages?: string[];
+    extensions: string[];
+    formats: string[];
+    frameworks: string[];
+    libraries: string[];
+    packageManager: string;
+    testing: string[];
+    tools: string[];
+    typescript: boolean;
+}
+interface V3MigrationOptions {
+    check?: boolean;
+    full?: boolean;
+    json?: boolean;
+    write?: boolean;
+}
+declare const getExplicitConfigFeaturePackages: (content: string) => string[];
+declare const migrateConfigToV3: (content: string, mode: "full" | "lean") => {
+    changes: string[];
+    content: string;
+    featurePackages: string[];
+};
+declare const handleMigrateV3: (cwd: string, context: V3MigrationContext, options?: V3MigrationOptions) => void;
+
+export { type V3MigrationContext, type V3MigrationOptions, getExplicitConfigFeaturePackages, handleMigrateV3, migrateConfigToV3 };