@santi020k/eslint-config-basic 3.1.0 → 3.2.0

package/dist/cli.js

@@ -11,6 +11,7 @@ import {
 } from "./agent-skill-generator.js";
 import { handleCompatibility, handleExplainRule } from "./cli-advanced.js";
 import { getExplicitConfigFeaturePackages, handleMigrateV3 } from "./cli-migration.js";
+import { handleExplainPreset } from "./cli-preset.js";
 import {
   handleBaseline,
   handleProfile,
@@ -157,7 +158,7 @@ const getInstallPackages = (summary, declaredDependencies, explicitFeaturePackag
   if (summary.typescript) packages.add(TYPESCRIPT_PACKAGE_NAME);
   return [...packages].filter((packageName) => !declaredDependencies.has(packageName));
 };
-const createInstallCommand = (packageManager, packages, workspaceRoot = false) => {
+const createInstallCommand = (packageManager, packages, workspaceRoot = false, catalog = false) => {
   const packageList = packages.join(" ");
   switch (packageManager) {
     case "bun":
@@ -167,10 +168,10 @@ const createInstallCommand = (packageManager, packages, workspaceRoot = false) =
     case "yarn":
       return `yarn add -D ${packageList}`;
     default:
-      return `pnpm add -D${workspaceRoot ? " --workspace-root" : ""} ${packageList}`;
+      return `pnpm add -D${workspaceRoot ? " --workspace-root" : ""}` + (catalog === true ? " --save-catalog" : "") + `${typeof catalog === "string" ? ` --save-catalog-name=${catalog}` : ""} ${packageList}`;
   }
 };
-const createInstallInvocation = (packageManager, packages, workspaceRoot = false) => {
+const createInstallInvocation = (packageManager, packages, workspaceRoot = false, catalog = false) => {
   switch (packageManager) {
     case "bun":
       return ["bun", ["add", "-d", ...packages]];
@@ -179,15 +180,134 @@ const createInstallInvocation = (packageManager, packages, workspaceRoot = false
     case "yarn":
       return ["yarn", ["add", "-D", ...packages]];
     default:
-      return ["pnpm", ["add", "-D", ...workspaceRoot ? ["--workspace-root"] : [], ...packages]];
+      return ["pnpm", [
+        "add",
+        "-D",
+        ...workspaceRoot ? ["--workspace-root"] : [],
+        ...catalog === true ? ["--save-catalog"] : [],
+        ...typeof catalog === "string" ? [`--save-catalog-name=${catalog}`] : [],
+        ...packages
+      ]];
+  }
+};
+const findPnpmWorkspaceRoot = (cwd) => {
+  let current = cwd;
+  for (; ; ) {
+    if (existsSync(join(current, "pnpm-workspace.yaml"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return void 0;
+    current = parent;
   }
 };
 const detectPackageManager = (cwd) => {
-  if (existsSync(join(cwd, "pnpm-lock.yaml")) || existsSync(join(cwd, "pnpm-workspace.yaml"))) return "pnpm";
+  if (findPnpmWorkspaceRoot(cwd) || existsSync(join(cwd, "pnpm-lock.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 getCatalogPreference = (packageJson) => {
+  const dependencyFields = ["devDependencies", "dependencies"];
+  const dependencyRecords = [];
+  const parseCatalog = (value) => {
+    if (typeof value !== "string" || !value.startsWith("catalog:")) return false;
+    const name = value.slice("catalog:".length);
+    return name && name !== "default" ? name : true;
+  };
+  for (const field of dependencyFields) {
+    const dependencies = packageJson?.[field];
+    if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies)) continue;
+    dependencyRecords.push(dependencies);
+  }
+  for (const dependencies of dependencyRecords) {
+    const basicCatalog = parseCatalog(Reflect.get(dependencies, BASIC_PACKAGE_NAME));
+    if (basicCatalog) return basicCatalog;
+  }
+  for (const dependencies of dependencyRecords) {
+    for (const value of Object.values(dependencies)) {
+      const catalog = parseCatalog(value);
+      if (catalog) return catalog;
+    }
+  }
+  return false;
+};
+const parseYamlMappingLine = (line) => {
+  const match = /^(\s*)(?:"([^"]+)"|'([^']+)'|([^'"].*?))\s*:\s*(.*?)\s*$/.exec(line);
+  if (!match) return void 0;
+  const value = match[5].replace(/\s+#.*$/, "").trim();
+  const key = match[2] || match[3] || match[4];
+  return {
+    indent: match[1].length,
+    key: key.trim(),
+    value: /^(['"]).*\1$/.test(value) ? value.slice(1, -1) : value
+  };
+};
+const getCatalogVersion = (workspaceRoot, packageName, catalog) => {
+  const workspacePath = join(workspaceRoot, "pnpm-workspace.yaml");
+  if (!existsSync(workspacePath)) return void 0;
+  const lines = readFileSync(workspacePath, "utf8").split(/\r?\n/);
+  let sectionIndex = -1;
+  let sectionIndent = -1;
+  if (catalog === true) {
+    sectionIndex = lines.findIndex((line) => {
+      const mapping = parseYamlMappingLine(line);
+      return mapping?.indent === 0 && mapping.key === "catalog" && mapping.value === "";
+    });
+    sectionIndent = 0;
+  } else {
+    const catalogsIndex = lines.findIndex((line) => {
+      const mapping = parseYamlMappingLine(line);
+      return mapping?.indent === 0 && mapping.key === "catalogs" && mapping.value === "";
+    });
+    if (catalogsIndex >= 0) {
+      for (let index = catalogsIndex + 1; index < lines.length; index++) {
+        const mapping = parseYamlMappingLine(lines.at(index) ?? "");
+        if (!mapping) continue;
+        if (mapping.indent === 0) break;
+        if (mapping.key === catalog && mapping.value === "") {
+          sectionIndex = index;
+          sectionIndent = mapping.indent;
+          break;
+        }
+      }
+    }
+  }
+  if (sectionIndex < 0) return void 0;
+  for (let index = sectionIndex + 1; index < lines.length; index++) {
+    const mapping = parseYamlMappingLine(lines.at(index) ?? "");
+    if (!mapping) continue;
+    if (mapping.indent <= sectionIndent) break;
+    if (mapping.key === packageName) return mapping.value || void 0;
+  }
+  return void 0;
+};
+const getCompatibleConfigVersion = (packageJson, workspaceRoot) => {
+  const dependencyFields = ["devDependencies", "dependencies", "peerDependencies"];
+  let basicSpec;
+  for (const field of dependencyFields) {
+    const dependencies = packageJson?.[field];
+    if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies)) continue;
+    const value = Object.entries(dependencies).find(([packageName]) => packageName === BASIC_PACKAGE_NAME)?.[1];
+    if (typeof value === "string") {
+      basicSpec = value;
+      break;
+    }
+  }
+  const catalogName = basicSpec?.startsWith("catalog:") ? basicSpec.slice("catalog:".length) : void 0;
+  let selectedCatalog;
+  if (catalogName !== void 0) {
+    selectedCatalog = catalogName && catalogName !== "default" ? catalogName : true;
+  }
+  const resolvedSpec = selectedCatalog && workspaceRoot ? getCatalogVersion(workspaceRoot, BASIC_PACKAGE_NAME, selectedCatalog) : basicSpec;
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(resolvedSpec ?? getCliVersion());
+  return match ? `^${match[1]}.${match[2]}.${match[3]}` : "^3.1.0";
+};
+const addCompatibleConfigVersions = (packages, version) => {
+  const major = /\d+/.exec(version)?.[0];
+  const companionVersion = major ? `^${major}.0.0` : version;
+  return packages.map(
+    (packageName) => packageName.startsWith("@santi020k/eslint-config-") && packageName !== LITE_PACKAGE_NAME && packageName !== INTEGRATIONS_PACKAGE_NAME ? `${packageName}@${packageName === BASIC_PACKAGE_NAME ? version : companionVersion}` : packageName
+  );
+};
 const hasLintScript = (cwd) => {
   const packageJson = readPackageJson(cwd);
   return Boolean(packageJson?.scripts?.lint);
@@ -237,13 +357,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 +372,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;
 };
@@ -297,7 +419,11 @@ const getProjectSummary = (cwd) => {
 };
 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];
   return {
     ...rootSummary,
@@ -368,6 +494,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",
@@ -387,7 +514,7 @@ const printUsage = () => {
     "  --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/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",
@@ -395,6 +522,8 @@ 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",
@@ -405,6 +534,94 @@ const printUsage = () => {
     "  --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"],
+  explain: ["--file", "--json"],
+  "explain-preset": ["--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) {
@@ -585,6 +802,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) => {
@@ -644,7 +871,7 @@ const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImpo
   checkDuplicateEslint(cwd, warnings);
   return { issues, warnings };
 };
-const outputDoctorResult = (json, configPath, packageManager, summary, liteInstallCommand, issues, warnings, fixes = []) => {
+const outputDoctorResult = (json, configPath, packageManager, summary, installCommand, requiredPackages, issues, warnings, fixes = []) => {
   let status = "passed";
   if (issues.length > 0) {
     status = "failed";
@@ -654,9 +881,10 @@ const outputDoctorResult = (json, configPath, packageManager, summary, liteInsta
   const payload = {
     configFile: configPath ? basename(configPath) : null,
     fixes,
+    ...installCommand ? { installCommand } : {},
     issues,
-    liteInstallCommand,
     packageManager,
+    requiredPackages,
     status,
     warnings,
     workspaceProjects: summary.workspaceProjects
@@ -671,6 +899,8 @@ 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}`] : [],
     ...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}`)] : []
@@ -742,18 +972,29 @@ const applyDoctorFixes = (cwd, packageJson, configPath, configContent, summary)
 };
 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 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, pnpmWorkspaceRoot)
+      ),
+      workspaceRoot,
+      catalog
+    );
     if (json) {
       console.log(JSON.stringify({ command: liteInstallCommand, packageManager, packages: liteInstallPackages }, null, 2));
     } else {
@@ -761,20 +1002,29 @@ const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = fal
     }
     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, pnpmWorkspaceRoot)
+    ),
+    workspaceRoot,
+    catalog
+  ) : void 0;
   const { issues, warnings } = buildDoctorDiagnosis(
-    cwd,
+    projectRoot,
     configPath,
     configContent,
     hasV1FrameworkImports,
@@ -782,41 +1032,74 @@ const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = fal
     declaredDependencies,
     summary
   );
-  outputDoctorResult(json, configPath, packageManager, summary, liteInstallCommand, issues, warnings, fixes);
+  outputDoctorResult(
+    json,
+    configPath,
+    packageManager,
+    summary,
+    installCommand,
+    requiredPackages,
+    issues,
+    warnings,
+    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, 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;
   }
 };
@@ -964,6 +1247,23 @@ 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, {
+        compatibility: flags.hasCompatibility,
+        file: flags.files[0],
+        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 +1365,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 +1375,18 @@ 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"),
     hasCheck: argv.includes("--check"),
+    hasCompatibility: argv.includes("--compatibility"),
     hasCreate: argv.includes("--create"),
     hasDryRun: argv.includes("--dry-run"),
     hasExplicit: argv.includes("--explicit"),
@@ -1093,8 +1401,10 @@ const runCli = (argv = process.argv, cwd = process.cwd()) => {
     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")
   });

package/dist/define-config-metadata.d.ts

@@ -0,0 +1,10 @@
+import { ConfigInput, EslintConfigOptions, FlatConfigArray } from '@santi020k/eslint-config-core';
+
+interface DefineConfigMetadata {
+    extraConfigs: ConfigInput[];
+    options?: EslintConfigOptions;
+}
+declare const attachDefineConfigMetadata: (config: FlatConfigArray, metadata: DefineConfigMetadata) => FlatConfigArray;
+declare const getDefineConfigMetadata: (config: unknown) => DefineConfigMetadata | undefined;
+
+export { type DefineConfigMetadata, attachDefineConfigMetadata, getDefineConfigMetadata };

package/dist/define-config-metadata.js

@@ -0,0 +1,18 @@
+const DEFINE_CONFIG_METADATA = /* @__PURE__ */ Symbol.for("@santi020k/eslint-config-basic/define-config-metadata");
+const attachDefineConfigMetadata = (config, metadata) => {
+  Object.defineProperty(config, DEFINE_CONFIG_METADATA, {
+    configurable: false,
+    enumerable: false,
+    value: metadata,
+    writable: false
+  });
+  return config;
+};
+const getDefineConfigMetadata = (config) => (
+  // eslint-disable-next-line security/detect-object-injection -- shared symbol is an internal fixed metadata key
+  Array.isArray(config) ? config[DEFINE_CONFIG_METADATA] : void 0
+);
+export {
+  attachDefineConfigMetadata,
+  getDefineConfigMetadata
+};

package/dist/frameworks.js

@@ -1,6 +1,7 @@
 import {
   createModuleLoader
 } from "@santi020k/eslint-config-core";
+import { isMissingRequestedPackage } from "./optional-package-errors.js";
 const loadModule = createModuleLoader((specifier) => import.meta.resolve(specifier, import.meta.url));
 const createDetectedFrameworkFlags = (detectedFrameworks = []) => Object.fromEntries(
   detectedFrameworks.map((framework) => [framework, true])
@@ -33,8 +34,10 @@ const loadFrameworkConfigInput = (frameworkName) => {
   if (!loader) return Promise.resolve([]);
   const pending = loader().catch((error) => {
     frameworkConfigCache.delete(frameworkName);
+    const specifier = `@santi020k/eslint-config-${frameworkName}`;
+    const remediation = isMissingRequestedPackage(error, specifier) ? `Install "${specifier}" or remove that framework from your defineConfig options.` : `The installed package "${specifier}" failed while evaluating. Inspect this error's cause for the original dependency or runtime failure.`;
     throw new Error(
-      `Unable to load optional framework config "${frameworkName}". Install "@santi020k/eslint-config-${frameworkName}" or remove that framework from your defineConfig options.`,
+      `Unable to load optional framework config "${frameworkName}". ` + remediation,
       { cause: error }
     );
   });