@santi020k/eslint-config-basic 3.2.0 → 3.3.0

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
+import { createRequire, findPackageJSON } from "node:module";
 import { basename, dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { findTailwindEntryPoint } from "@santi020k/eslint-config-core";
 import {
   analyzeEslintConfig,
   ESLINT_CONFIG_FILENAMES,
@@ -11,6 +12,15 @@ import {
 } from "./agent-skill-generator.js";
 import { handleCompatibility, handleExplainRule } from "./cli-advanced.js";
 import { getExplicitConfigFeaturePackages, handleMigrateV3 } from "./cli-migration.js";
+import {
+  addCompatibleConfigVersions,
+  createInstallCommand,
+  createInstallInvocation,
+  detectPackageManager,
+  findPnpmWorkspaceRoot,
+  getCatalogPreference,
+  getCompatibleConfigVersion
+} from "./cli-package-manager.js";
 import { handleExplainPreset } from "./cli-preset.js";
 import {
   handleBaseline,
@@ -19,6 +29,7 @@ import {
   handleSnapshotDiff
 } from "./cli-workflows.js";
 import { detectProjectOptions } from "./index.js";
+import { findCssComponentClasses } from "./tailwind.js";
 const getDefaultConfigFilename = (cwd) => {
   const packageJsonPath = join(cwd, "package.json");
   if (!existsSync(packageJsonPath)) return "eslint.config.mjs";
@@ -81,6 +92,13 @@ const CATEGORY_PACKAGES = {
   testing: "@santi020k/eslint-config-testing",
   tools: "@santi020k/eslint-config-tools"
 };
+const PRESET_INSTALL_PACKAGES = {
+  all: Object.values(CATEGORY_PACKAGES),
+  app: [CATEGORY_PACKAGES.testing, CATEGORY_PACKAGES.tools],
+  ci: [CATEGORY_PACKAGES.extensions, CATEGORY_PACKAGES.tools],
+  library: [CATEGORY_PACKAGES.extensions, CATEGORY_PACKAGES.tools],
+  monorepo: [CATEGORY_PACKAGES.extensions, CATEGORY_PACKAGES.tools]
+};
 const getConfigPathIfPresent = (cwd) => {
   const configPath = ESLINT_CONFIG_FILENAMES.map((filename) => join(cwd, filename)).find((p) => existsSync(p));
   return configPath ?? null;
@@ -154,160 +172,13 @@ const getInstallPackages = (summary, declaredDependencies, explicitFeaturePackag
     for (const packageName of explicitFeaturePackages) {
       packages.add(packageName);
     }
+    for (const packageName of PRESET_INSTALL_PACKAGES[summary.preset] ?? []) {
+      packages.add(packageName);
+    }
   }
   if (summary.typescript) packages.add(TYPESCRIPT_PACKAGE_NAME);
   return [...packages].filter((packageName) => !declaredDependencies.has(packageName));
 };
-const createInstallCommand = (packageManager, packages, workspaceRoot = false, catalog = false) => {
-  const packageList = packages.join(" ");
-  switch (packageManager) {
-    case "bun":
-      return `bun add -d ${packageList}`;
-    case "npm":
-      return `npm install -D ${packageList}`;
-    case "yarn":
-      return `yarn add -D ${packageList}`;
-    default:
-      return `pnpm add -D${workspaceRoot ? " --workspace-root" : ""}` + (catalog === true ? " --save-catalog" : "") + `${typeof catalog === "string" ? ` --save-catalog-name=${catalog}` : ""} ${packageList}`;
-  }
-};
-const createInstallInvocation = (packageManager, packages, workspaceRoot = false, catalog = 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"] : [],
-        ...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 (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);
@@ -402,6 +273,10 @@ const formatList = (values) => {
 const getProjectSummary = (cwd) => {
   const options = detectProjectOptions(cwd);
   const workspaceProjects = detectWorkspaceProjects(cwd);
+  let typescriptMode = "off";
+  if (options.typescript) {
+    typescriptMode = options.typescript === "syntax" ? "syntax" : "type-aware";
+  }
   return {
     detectedProjects: Object.keys(options.projects ?? {}).sort(),
     extensions: options.extensions ?? [],
@@ -414,9 +289,42 @@ const getProjectSummary = (cwd) => {
     testing: options.testing ?? [],
     tools: options.tools ?? [],
     typescript: Boolean(options.typescript),
+    typescriptMode,
     workspaceProjects
   };
 };
+const getDetectedProjectPaths = (cwd) => {
+  const summary = getProjectSummary(cwd);
+  return summary.workspaceProjects.length > 0 ? [.../* @__PURE__ */ new Set([...summary.detectedProjects, ...summary.workspaceProjects])] : ["."];
+};
+const getTailwindUnknownClassPolicy = (detected, entryPoint, componentClasses = 0) => {
+  if (!detected) return "off";
+  if (!entryPoint) return "fallback-off";
+  return componentClasses > 0 ? "strict-with-css-components" : "strict";
+};
+const getTailwindEntryPoints = (cwd) => getDetectedProjectPaths(cwd).flatMap((projectPath) => {
+  const projectRoot = projectPath === "." ? cwd : join(cwd, projectPath);
+  const summary = getProjectSummary(projectRoot);
+  if (!summary.libraries.includes("tailwind")) return [];
+  const entryPoint = findTailwindEntryPoint(projectRoot) ?? null;
+  const componentClasses = entryPoint ? findCssComponentClasses(projectRoot, entryPoint).length : 0;
+  return [{
+    componentClasses,
+    entryPoint,
+    path: projectPath,
+    unknownClassPolicy: getTailwindUnknownClassPolicy(true, entryPoint, componentClasses)
+  }];
+});
+const getDeclarationProjectWarnings = (cwd) => getDetectedProjectPaths(cwd).flatMap((projectPath) => {
+  const projectRoot = projectPath === "." ? cwd : join(cwd, projectPath);
+  const summary = getProjectSummary(projectRoot);
+  if (summary.typescriptMode !== "syntax") return [];
+  const packageName = readPackageJson(projectRoot)?.name;
+  const packageLabel = typeof packageName === "string" ? `${projectPath} (${packageName})` : projectPath;
+  return [
+    `TypeScript declarations were detected in ${packageLabel}, but no supported package-local tsconfig was found. The package uses syntax-only linting to avoid a project-service parse failure. Add a tsconfig.json that includes the declarations for type-aware linting, or add their patterns to \`typescript.untypedFiles\` when a parent type-aware project intentionally owns them.`
+  ];
+});
 const getInstallProjectSummary = (cwd) => {
   const rootSummary = getProjectSummary(cwd);
   const projectPaths = [.../* @__PURE__ */ new Set([
@@ -425,6 +333,12 @@ const getInstallProjectSummary = (cwd) => {
   ])];
   const projectSummaries = projectPaths.map((projectPath) => getProjectSummary(join(cwd, projectPath)));
   const summaries = [rootSummary, ...projectSummaries];
+  let typescriptMode = "off";
+  if (summaries.some((summary) => summary.typescriptMode === "type-aware")) {
+    typescriptMode = "type-aware";
+  } else if (summaries.some((summary) => summary.typescriptMode === "syntax")) {
+    typescriptMode = "syntax";
+  }
   return {
     ...rootSummary,
     extensions: [...new Set(summaries.flatMap((summary) => summary.extensions))],
@@ -433,7 +347,8 @@ const getInstallProjectSummary = (cwd) => {
     libraries: [...new Set(summaries.flatMap((summary) => summary.libraries))],
     testing: [...new Set(summaries.flatMap((summary) => summary.testing))],
     tools: [...new Set(summaries.flatMap((summary) => summary.tools))],
-    typescript: summaries.some((summary) => summary.typescript)
+    typescript: summaries.some((summary) => summary.typescript),
+    typescriptMode
   };
 };
 const getWorkspaceDeclaredConfigPackages = (cwd, summary) => {
@@ -508,13 +423,14 @@ const printUsage = () => {
     "  generate-skill  Generate AI agent standards files",
     "",
     "Options:",
+    "  --analyze-source explain-preset: lint source and preview autofix without writing",
     "  --force         Overwrite existing generated skill sections/files",
     "  --check         Verify generated files, migrations, or snapshots without writing",
     "  --concurrency   profile: off, auto, or a worker count",
     "  --create        generate-skill: scaffold a root AGENTS.md when missing",
     "  --dry-run       install: print the detected install command without running it",
     "  --explicit      init: write detected settings explicitly",
-    "  --file          explain/profile/snapshot/diff: representative file or lint target (repeatable)",
+    "  --file          explain/explain-preset/profile/snapshot/diff: file or lint target (repeatable)",
     "  --fix           doctor: safely repair generated config and package metadata",
     "  --full          migrate --to v3: choose the batteries-included package",
     "  --json          Print JSON for commands that support it",
@@ -528,6 +444,7 @@ const printUsage = () => {
     "  --prune         baseline: remove suppressions for resolved violations",
     "  --snapshot-path snapshot/diff: override .eslint-config-snapshot.json",
     "  --to            migrate: target version (v2 or v3)",
+    "  --verbose       doctor: print per-project activation details",
     "  --with-eslint-mcp generate-skill: scaffold the official ESLint MCP server",
     "  --write         Apply safe migrations for commands that support it",
     "  --help, -h      Show this help message",
@@ -539,9 +456,9 @@ const COMMAND_OPTIONS = {
   compatibility: ["--json"],
   diff: ["--file", "--json", "--snapshot-path"],
   docs: [],
-  doctor: ["--fix", "--json", "--lite-install"],
+  doctor: ["--fix", "--json", "--lite-install", "--verbose"],
   explain: ["--file", "--json"],
-  "explain-preset": ["--compatibility", "--file", "--json", "--output"],
+  "explain-preset": ["--analyze-source", "--compatibility", "--file", "--json", "--output"],
   "generate-skill": ["--check", "--create", "--force", "--with-eslint-mcp"],
   init: ["--check", "--explicit"],
   inspect: ["--json"],
@@ -683,7 +600,8 @@ const handleInspect = async (cwd = process.cwd(), json = false) => {
   const payload = {
     activeConfig,
     detected: summary,
-    packageManager: detectPackageManager(cwd)
+    packageManager: detectPackageManager(cwd),
+    tailwindEntryPoints: getTailwindEntryPoints(cwd)
   };
   if (json) {
     console.log(JSON.stringify(payload, null, 2));
@@ -707,31 +625,135 @@ const handleInspect = async (cwd = process.cwd(), json = false) => {
   ].join("\n"));
 };
 const semver = createRequire(import.meta.url)("semver");
-const readPackageMetadataFromMain = (mainPath, packageName) => {
+const intersectTwoSemverRanges = (left, right) => {
+  if (semver.subset(left, right)) return left;
+  if (semver.subset(right, left)) return right;
+  const intersections = /* @__PURE__ */ new Set();
+  const leftRange = new semver.Range(left);
+  const rightRange = new semver.Range(right);
+  for (const leftComparators of leftRange.set) {
+    for (const rightComparators of rightRange.set) {
+      const candidate = [...leftComparators, ...rightComparators].map((comparator) => comparator.value).filter(Boolean).join(" ");
+      const normalized = new semver.Range(candidate || "*").range || "*";
+      if (semver.minVersion(normalized)) intersections.add(normalized);
+    }
+  }
+  return intersections.size > 0 ? [...intersections].join(" || ") : null;
+};
+const intersectSemverRanges = (ranges) => {
+  const validRanges = ranges.filter((range) => semver.validRange(range) !== null);
+  if (validRanges.length !== ranges.length || validRanges.length === 0) return null;
+  let intersection = validRanges[0];
+  for (const range of validRanges.slice(1)) {
+    intersection = intersectTwoSemverRanges(intersection, range) ?? "";
+    if (!intersection) return null;
+  }
+  return intersection;
+};
+const readPackageMetadataFromMain = (mainPath) => {
   let directory = dirname(mainPath);
   for (let depth = 0; depth < 4; depth++) {
     const packagePath = join(directory, "package.json");
     if (existsSync(packagePath)) {
       const metadata = JSON.parse(readFileSync(packagePath, "utf8"));
-      if (metadata.name === packageName) return metadata;
+      if (metadata.name && metadata.version) return metadata;
     }
     directory = dirname(directory);
   }
   return null;
 };
 const resolvePackageMetadata = (cwd, packageName) => {
-  try {
-    const projectRequire = createRequire(join(cwd, "package.json"));
+  const candidateRoots = [...new Set([
+    cwd,
+    findPnpmWorkspaceRoot(cwd)
+  ].filter((root) => Boolean(root)))];
+  for (const candidateRoot of candidateRoots) {
     try {
-      return readPackageMetadataFromMain(projectRequire.resolve(packageName), packageName);
+      const manifestPath = findPackageJSON(
+        packageName,
+        pathToFileURL(join(candidateRoot, "package.json"))
+      );
+      if (manifestPath) {
+        const metadata = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return metadata;
+      }
     } catch {
-      const integrationsMain = projectRequire.resolve(INTEGRATIONS_PACKAGE_NAME);
-      const integrationsRequire = createRequire(integrationsMain);
-      return readPackageMetadataFromMain(integrationsRequire.resolve(packageName), packageName);
     }
-  } catch {
-    return null;
+    try {
+      const projectRequire = createRequire(join(candidateRoot, "package.json"));
+      try {
+        const metadata = readPackageMetadataFromMain(projectRequire.resolve(packageName));
+        if (metadata) return metadata;
+      } catch {
+        const integrationsMain = projectRequire.resolve(INTEGRATIONS_PACKAGE_NAME);
+        const integrationsRequire = createRequire(integrationsMain);
+        const metadata = readPackageMetadataFromMain(integrationsRequire.resolve(packageName));
+        if (metadata) return metadata;
+      }
+    } catch {
+    }
+    for (const projectPath of detectWorkspaceProjects(candidateRoot)) {
+      const metadata = readPackageJson(join(candidateRoot, projectPath));
+      if (metadata?.name === packageName) return metadata;
+    }
+  }
+  return null;
+};
+const assessConsumerNodeEngine = (cwd, packageJson) => {
+  const declaredConfigPackages = [...getDeclaredDependencyNames(packageJson)].filter((packageName) => packageName.startsWith("@santi020k/eslint-config-"));
+  const requiredRanges = declaredConfigPackages.flatMap((packageName) => {
+    const range = resolvePackageMetadata(cwd, packageName)?.engines?.node;
+    return range ? [range] : [];
+  });
+  const requiredRange = intersectSemverRanges(requiredRanges);
+  const engines = packageJson?.engines;
+  const consumerRange = engines && typeof engines === "object" && !Array.isArray(engines) ? engines.node : null;
+  const normalizedConsumerRange = typeof consumerRange === "string" ? consumerRange : null;
+  if (requiredRanges.length === 0) {
+    return {
+      compatible: true,
+      consumerRange: normalizedConsumerRange,
+      requiredRange: null,
+      targetRange: null
+    };
+  }
+  if (!requiredRange) {
+    return {
+      compatible: false,
+      consumerRange: normalizedConsumerRange,
+      requiredRange: null,
+      targetRange: null
+    };
   }
+  if (!normalizedConsumerRange || !semver.validRange(normalizedConsumerRange)) {
+    return {
+      compatible: false,
+      consumerRange: normalizedConsumerRange,
+      requiredRange,
+      targetRange: requiredRange
+    };
+  }
+  const compatible = requiredRanges.every((range) => semver.subset(normalizedConsumerRange, range));
+  return {
+    compatible,
+    consumerRange: normalizedConsumerRange,
+    requiredRange,
+    targetRange: compatible ? null : intersectSemverRanges([normalizedConsumerRange, ...requiredRanges])
+  };
+};
+const getConsumerNodeEngineWarning = (cwd, packageJson) => {
+  const assessment = assessConsumerNodeEngine(cwd, packageJson);
+  if (assessment.compatible) return null;
+  if (!assessment.requiredRange) {
+    return "Installed config packages do not share a compatible Node engine range.";
+  }
+  if (!assessment.consumerRange) {
+    return `package.json does not declare engines.node; installed config packages require ${assessment.requiredRange}.`;
+  }
+  if (!semver.validRange(assessment.consumerRange)) {
+    return `package.json engines.node ${assessment.consumerRange} is invalid; installed config packages require ${assessment.requiredRange}.`;
+  }
+  return `package.json engines.node ${assessment.consumerRange} permits unsupported runtimes; installed config packages require ${assessment.requiredRange}.`;
 };
 const getAstroDoctorNodeWarning = (metadata) => {
   const nodeRange = metadata.engines?.node;
@@ -779,7 +801,11 @@ const validateConfigContent = (configContent, hasV1FrameworkImports, declaredDep
   if (hasV1FrameworkImports) {
     warnings.push("Config still imports v1 framework packages. Run `basic-eslint migrate --write` or switch to framework booleans.");
   }
-  const usesBasicComposer = /from\s*['"]@santi020k\/eslint-config-(?:basic|full|lite)['"]/.test(configContent) && /\b(?:defineConfig|eslintConfig)\s*\(/.test(configContent);
+  const usesComposerCall = /from\s*['"]@santi020k\/eslint-config-(?:basic|full|lite)['"]/.test(configContent) && /\b(?:defineConfig|eslintConfig)\s*\(/.test(configContent);
+  const usesRecommendedComposer = /from\s*['"]@santi020k\/eslint-config-(?:basic|full)\/recommended['"]/.test(
+    configContent
+  );
+  const usesBasicComposer = usesComposerCall || usesRecommendedComposer;
   const hasDetectedProjectScopes = summary.workspaceProjects.every((project) => summary.detectedProjects.includes(project));
   if (summary.workspaceProjects.length > 0 && !configContent.includes("projects:") && !(usesBasicComposer && hasDetectedProjectScopes)) {
     warnings.push("Workspace packages were detected, but the root config does not use `projects` scoping.");
@@ -861,7 +887,13 @@ const checkDuplicateEslint = (cwd, warnings) => {
     );
   }
 };
-const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary) => {
+const getTailwindEntryPointWarnings = (cwd) => getTailwindEntryPoints(cwd).flatMap(({ entryPoint, path: projectPath }) => {
+  if (entryPoint) return [];
+  return [
+    `Tailwind CSS was detected in ${projectPath}, but no conventional CSS entry point was found. \`better-tailwindcss/no-unknown-classes\` falls back to off; set \`tailwind.entryPoint\` to enable strict validation or \`tailwind.noUnknownClasses: false\` to document a mixed CSS system.`
+  ];
+});
+const buildDoctorDiagnosis = (cwd, packageJson, configPath, configContent, hasV1FrameworkImports, activeConfig, declaredDependencies, summary) => {
   const { issues, warnings } = validateProjectSetup(cwd, configPath, activeConfig, hasV1FrameworkImports);
   if (configContent) {
     warnings.push(...validateConfigContent(configContent, hasV1FrameworkImports, declaredDependencies, summary));
@@ -869,9 +901,238 @@ const buildDoctorDiagnosis = (cwd, configPath, configContent, hasV1FrameworkImpo
   const astroDoctorEnabled = checkAstroDoctorStatus(activeConfig, configContent, summary, warnings);
   warnings.push(...getAstroDoctorCompatibilityWarnings(cwd, astroDoctorEnabled));
   checkDuplicateEslint(cwd, warnings);
+  warnings.push(...getDeclarationProjectWarnings(cwd));
+  warnings.push(...getTailwindEntryPointWarnings(cwd));
+  const nodeEngineWarning = getConsumerNodeEngineWarning(cwd, packageJson);
+  if (nodeEngineWarning) warnings.push(nodeEngineWarning);
   return { issues, warnings };
 };
-const outputDoctorResult = (json, configPath, packageManager, summary, installCommand, requiredPackages, issues, warnings, fixes = []) => {
+const DOCTOR_FEATURE_ALIASES = {
+  "astro-doctor": "Astro Doctor",
+  "best-practices": "Best Practices",
+  compat: "Browser Compat",
+  nest: "NestJS",
+  next: "Next.js",
+  node: "Node.js",
+  solid: "SolidJS",
+  "tanstack-start": "TanStack Start",
+  tailwind: "Tailwind CSS"
+};
+const normalizeDoctorFeature = (value) => {
+  const comparableValue = DOCTOR_FEATURE_ALIASES[value] ?? value;
+  return comparableValue.toLowerCase().replaceAll(/[^a-z0-9]/g, "");
+};
+const isDoctorFeatureEnabled = (name, enabled) => {
+  const normalizedName = normalizeDoctorFeature(name);
+  return enabled.some((value) => normalizeDoctorFeature(value) === normalizedName);
+};
+const getTypeScriptConfig = (cwd) => [
+  "tsconfig.json",
+  "tsconfig.base.json",
+  "tsconfig.app.json",
+  "tsconfig.node.json",
+  "tsconfig.eslint.json"
+].find((fileName) => existsSync(join(cwd, fileName))) ?? null;
+const getCategoryPackageInstalled = (cwd, packageName) => [
+  packageName,
+  INTEGRATIONS_PACKAGE_NAME,
+  FULL_PACKAGE_NAME
+].some((candidate) => resolvePackageMetadata(cwd, candidate) !== null);
+const createDoctorFeatureActivations = (cwd, category, detected, enabled, includeEnabled = false) => {
+  const names = [...detected];
+  if (includeEnabled) {
+    for (const enabledName of enabled) {
+      if (!isDoctorFeatureEnabled(enabledName, names)) names.push(enabledName);
+    }
+  }
+  return names.map((name) => {
+    const packageName = category === "frameworks" ? Object.entries(FRAMEWORK_KEY_TO_PACKAGE).find(([framework]) => isDoctorFeatureEnabled(name, [framework]))?.[1] : CATEGORY_PACKAGES[category];
+    if (!packageName) throw new Error(`Unknown doctor ${category} feature: ${name}`);
+    const installed = getCategoryPackageInstalled(cwd, packageName);
+    const isDetected = isDoctorFeatureEnabled(name, detected);
+    const isEnabled = installed && isDoctorFeatureEnabled(name, enabled);
+    let reason;
+    if (!installed) {
+      reason = isDetected ? `Detected, but ${packageName} is not installed.` : `Enabled in the active config, but ${packageName} is not installed.`;
+    } else if (!isEnabled) {
+      reason = "Detected and installed, but the active config did not load this pack.";
+    }
+    return {
+      detected: isDetected,
+      enabled: isEnabled,
+      installed,
+      name,
+      package: packageName,
+      ...reason ? { reason } : {}
+    };
+  });
+};
+const getInactiveDoctorPackages = (cwd, detectedFrameworks, summary, activeConfig) => {
+  const inactivePackages = Object.entries(FRAMEWORK_KEY_TO_PACKAGE).filter(([framework, packageName]) => !detectedFrameworks.includes(framework) && !isDoctorFeatureEnabled(framework, activeConfig?.frameworks ?? []) && resolvePackageMetadata(cwd, packageName) !== null).map(([, packageName]) => ({
+    package: packageName,
+    reason: "Installed, but no matching framework signal was detected in this project."
+  }));
+  for (const [category, packageName] of Object.entries(CATEGORY_PACKAGES)) {
+    if (summary[category].length === 0 && (activeConfig?.[category]?.length ?? 0) === 0 && resolvePackageMetadata(cwd, packageName) !== null) {
+      inactivePackages.push({
+        package: packageName,
+        reason: `Installed, but no ${category} signals were detected in this project.`
+      });
+    }
+  }
+  return inactivePackages;
+};
+const getDoctorProjectActivations = async (cwd) => {
+  const rootSummary = getProjectSummary(cwd);
+  const projectPaths = [.../* @__PURE__ */ new Set([
+    ".",
+    ...rootSummary.detectedProjects,
+    ...rootSummary.workspaceProjects
+  ])].sort((left, right) => {
+    if (left === ".") return -1;
+    if (right === ".") return 1;
+    return left.localeCompare(right);
+  });
+  return Promise.all(projectPaths.map(async (projectPath) => {
+    const projectRoot = projectPath === "." ? cwd : join(cwd, projectPath);
+    const summary = getProjectSummary(projectRoot);
+    const projectActiveConfig = await analyzeEslintConfig(cwd, { projectPath, projectPaths }) ?? void 0;
+    const tsconfig = getTypeScriptConfig(projectRoot);
+    const typescriptInstalled = resolvePackageMetadata(projectRoot, TYPESCRIPT_PACKAGE_NAME) !== null;
+    const typescriptEnabled = summary.typescript && Boolean(projectActiveConfig?.typescript);
+    const tailwindDetected = summary.libraries.includes("tailwind");
+    const tailwindEntryPoint = tailwindDetected ? findTailwindEntryPoint(projectRoot) ?? null : null;
+    const tailwindComponentClasses = tailwindEntryPoint ? findCssComponentClasses(projectRoot, tailwindEntryPoint).length : 0;
+    let typescriptMode = "off";
+    let typescriptReason;
+    if (typescriptEnabled) {
+      typescriptMode = summary.typescriptMode;
+    }
+    if (!typescriptInstalled && summary.typescript) {
+      typescriptReason = summary.typescriptMode === "syntax" ? "TypeScript declarations were detected, but TypeScript is not installed." : "A tsconfig was detected, but TypeScript is not installed.";
+    } else if (typescriptInstalled && !summary.typescript) {
+      typescriptReason = "Installed, but no supported tsconfig was detected in this project.";
+    } else if (typescriptInstalled && summary.typescript && !typescriptEnabled) {
+      typescriptReason = "Detected and installed, but the active config did not enable TypeScript.";
+    }
+    return {
+      extensions: createDoctorFeatureActivations(
+        projectRoot,
+        "extensions",
+        summary.extensions,
+        projectActiveConfig?.extensions ?? [],
+        true
+      ),
+      formats: createDoctorFeatureActivations(
+        projectRoot,
+        "formats",
+        summary.formats,
+        projectActiveConfig?.formats ?? [],
+        true
+      ),
+      frameworks: createDoctorFeatureActivations(
+        projectRoot,
+        "frameworks",
+        summary.frameworks,
+        projectActiveConfig?.frameworks ?? [],
+        true
+      ),
+      ignores: projectActiveConfig?.ignores ?? [],
+      inactivePackages: getInactiveDoctorPackages(projectRoot, summary.frameworks, summary, projectActiveConfig),
+      libraries: createDoctorFeatureActivations(
+        projectRoot,
+        "libraries",
+        summary.libraries,
+        projectActiveConfig?.libraries ?? [],
+        true
+      ),
+      path: projectPath,
+      runtime: summary.runtime,
+      tailwind: {
+        componentClasses: tailwindComponentClasses,
+        detected: tailwindDetected,
+        entryPoint: tailwindEntryPoint,
+        unknownClassPolicy: getTailwindUnknownClassPolicy(
+          tailwindDetected,
+          tailwindEntryPoint,
+          tailwindComponentClasses
+        )
+      },
+      testing: createDoctorFeatureActivations(
+        projectRoot,
+        "testing",
+        summary.testing,
+        projectActiveConfig?.testing ?? [],
+        true
+      ),
+      tools: createDoctorFeatureActivations(
+        projectRoot,
+        "tools",
+        summary.tools,
+        projectActiveConfig?.tools ?? [],
+        true
+      ),
+      typescript: {
+        detected: summary.typescript,
+        enabled: typescriptEnabled,
+        installed: typescriptInstalled,
+        mode: typescriptMode,
+        package: TYPESCRIPT_PACKAGE_NAME,
+        ...typescriptReason ? { reason: typescriptReason } : {},
+        tsconfig
+      }
+    };
+  }));
+};
+const formatDoctorActivation = (features) => features.length === 0 ? "none" : features.map((feature) => {
+  const states = [
+    feature.installed ? "I" : "-",
+    feature.detected ? "D" : "-",
+    feature.enabled ? "E" : "-"
+  ].join("");
+  return `${feature.name}[${states}]`;
+}).join(",");
+const formatDoctorProjectTable = (projects) => [
+  "",
+  "Per-project activation (I=installed, D=detected, E=enabled):",
+  "Project | Runtime | TypeScript | Tailwind entry | Frameworks | Formats | Libraries | Extensions | Testing | Tools | Ignores",
+  "--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---",
+  ...projects.flatMap((project) => {
+    const typescriptStates = [
+      project.typescript.installed ? "I" : "-",
+      project.typescript.detected ? "D" : "-",
+      project.typescript.enabled ? "E" : "-"
+    ].join("");
+    const row = [
+      project.path,
+      project.runtime,
+      `${project.typescript.mode}:${project.typescript.tsconfig ?? "none"}[${typescriptStates}]`,
+      project.tailwind.componentClasses > 0 ? `${project.tailwind.entryPoint ?? "none"} (${project.tailwind.componentClasses} CSS classes)` : project.tailwind.entryPoint ?? "none",
+      formatDoctorActivation(project.frameworks),
+      formatDoctorActivation(project.formats),
+      formatDoctorActivation(project.libraries),
+      formatDoctorActivation(project.extensions),
+      formatDoctorActivation(project.testing),
+      formatDoctorActivation(project.tools),
+      formatList(project.ignores)
+    ].join(" | ");
+    const explanations = [
+      project.typescript.reason,
+      ...project.frameworks.map((feature) => feature.reason),
+      ...project.formats.map((feature) => feature.reason),
+      ...project.libraries.map((feature) => feature.reason),
+      ...project.extensions.map((feature) => feature.reason),
+      ...project.testing.map((feature) => feature.reason),
+      ...project.tools.map((feature) => feature.reason),
+      ...project.inactivePackages.map((item) => `${item.package}: ${item.reason}`)
+    ].filter((reason) => Boolean(reason));
+    return [
+      row,
+      ...explanations.map((reason) => `  ${project.path}: ${reason}`)
+    ];
+  })
+];
+const outputDoctorResult = (json, verbose, configPath, packageManager, summary, installCommand, requiredPackages, issues, warnings, projects, fixes = []) => {
   let status = "passed";
   if (issues.length > 0) {
     status = "failed";
@@ -884,6 +1145,7 @@ const outputDoctorResult = (json, configPath, packageManager, summary, installCo
     ...installCommand ? { installCommand } : {},
     issues,
     packageManager,
+    projects,
     requiredPackages,
     status,
     warnings,
@@ -901,6 +1163,7 @@ const outputDoctorResult = (json, configPath, packageManager, summary, installCo
     `- Workspace projects: ${formatList(summary.workspaceProjects)}`,
     `- Required packages: ${formatList(requiredPackages)}`,
     ...installCommand ? [`- Install command: ${installCommand}`] : [],
+    ...verbose ? formatDoctorProjectTable(projects) : [],
     ...fixes.length > 0 ? ["", "Fixes applied:", ...fixes.map((fix) => `- ${fix}`)] : [],
     ...issues.length > 0 ? ["", "Issues:", ...issues.map((issue) => `- ${issue}`)] : [],
     ...warnings.length > 0 ? ["", "Warnings:", ...warnings.map((warning) => `- ${warning}`)] : []
@@ -945,6 +1208,15 @@ const applyDoctorFixes = (cwd, packageJson, configPath, configContent, summary)
       fixes.push(`Declared ${packageName}.`);
       packageChanged = true;
     }
+    const nodeEngine = assessConsumerNodeEngine(cwd, packageJson);
+    if (!nodeEngine.compatible && nodeEngine.targetRange) {
+      updated.engines ??= {};
+      updated.engines.node = nodeEngine.targetRange;
+      packageChanged = true;
+      fixes.push(
+        nodeEngine.consumerRange ? `Changed engines.node from ${nodeEngine.consumerRange} to ${nodeEngine.targetRange}.` : `Declared engines.node as ${nodeEngine.targetRange}.`
+      );
+    }
     if (packageChanged) {
       const packagePath = join(cwd, "package.json");
       const backupPath = createDoctorBackupPath(packagePath);
@@ -971,7 +1243,7 @@ const applyDoctorFixes = (cwd, packageJson, configPath, configContent, summary)
   return fixes;
 };
 const hasV1FrameworkPackageImports = (configContent) => configContent !== null && Object.keys(FRAMEWORK_PACKAGE_TO_KEY).some((packageName) => configContent.includes(packageName));
-const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = false, fix = false) => {
+const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = false, fix = false, verbose = false) => {
   const pnpmWorkspaceRoot = findPnpmWorkspaceRoot(cwd);
   const projectRoot = pnpmWorkspaceRoot ?? cwd;
   const packageManager = detectPackageManager(projectRoot);
@@ -990,13 +1262,17 @@ const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = fal
       packageManager,
       addCompatibleConfigVersions(
         liteInstallPackages,
-        getCompatibleConfigVersion(packageJson, pnpmWorkspaceRoot)
+        getCompatibleConfigVersion(packageJson, getCliVersion(), pnpmWorkspaceRoot)
       ),
       workspaceRoot,
       catalog
     );
     if (json) {
-      console.log(JSON.stringify({ command: liteInstallCommand, packageManager, packages: liteInstallPackages }, null, 2));
+      console.log(JSON.stringify({
+        command: liteInstallCommand,
+        packageManager,
+        packages: liteInstallPackages
+      }, null, 2));
     } else {
       console.log(liteInstallCommand);
     }
@@ -1018,13 +1294,14 @@ const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = fal
     packageManager,
     addCompatibleConfigVersions(
       requiredPackages,
-      getCompatibleConfigVersion(packageJson, pnpmWorkspaceRoot)
+      getCompatibleConfigVersion(packageJson, getCliVersion(), pnpmWorkspaceRoot)
     ),
     workspaceRoot,
     catalog
   ) : void 0;
   const { issues, warnings } = buildDoctorDiagnosis(
     projectRoot,
+    packageJson,
     configPath,
     configContent,
     hasV1FrameworkImports,
@@ -1032,8 +1309,10 @@ const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = fal
     declaredDependencies,
     summary
   );
+  const projects = await getDoctorProjectActivations(projectRoot);
   outputDoctorResult(
     json,
+    verbose,
     configPath,
     packageManager,
     summary,
@@ -1041,6 +1320,7 @@ const handleDoctor = async (cwd = process.cwd(), json = false, liteInstall = fal
     requiredPackages,
     issues,
     warnings,
+    projects,
     fixes
   );
 };
@@ -1066,7 +1346,7 @@ const handleInstall = (cwd = process.cwd(), dryRun = false, runner = spawnSync)
   const catalog = workspaceRoot ? getCatalogPreference(packageJson) : false;
   const installPackages = addCompatibleConfigVersions(
     packages,
-    getCompatibleConfigVersion(packageJson, pnpmWorkspaceRoot)
+    getCompatibleConfigVersion(packageJson, getCliVersion(), pnpmWorkspaceRoot)
   );
   if (packages.length === 0) {
     console.log("\u2705 All packages required by the detected ESLint configuration are already declared.");
@@ -1226,7 +1506,7 @@ const dispatchCommand = (command, cwd, flags) => {
       break;
     }
     case "doctor": {
-      handleDoctor(cwd, flags.hasJson, flags.hasLiteInstall, flags.hasFix).catch((error) => {
+      handleDoctor(cwd, flags.hasJson, flags.hasLiteInstall, flags.hasFix, flags.hasVerbose).catch((error) => {
         console.error(`\u274C Failed to run doctor: ${String(error)}`);
         process.exitCode = 1;
       });
@@ -1254,8 +1534,10 @@ const dispatchCommand = (command, cwd, flags) => {
         break;
       }
       handleExplainPreset(cwd, flags.positional, {
+        analyzeSource: flags.hasAnalyzeSource,
         compatibility: flags.hasCompatibility,
         file: flags.files[0],
+        files: flags.files,
         json: flags.hasJson,
         output: flags.output
       }).catch((error) => {
@@ -1385,6 +1667,7 @@ const runCli = (argv = process.argv, cwd = process.cwd()) => {
   dispatchCommand(command, cwd, {
     concurrency: getFlagValue(argv, "--concurrency"),
     files: getFlagValues(argv, "--file"),
+    hasAnalyzeSource: argv.includes("--analyze-source"),
     hasCheck: argv.includes("--check"),
     hasCompatibility: argv.includes("--compatibility"),
     hasCreate: argv.includes("--create"),
@@ -1396,6 +1679,7 @@ const runCli = (argv = process.argv, cwd = process.cwd()) => {
     hasJson: argv.includes("--json"),
     hasLiteInstall: argv.includes("--lite-install"),
     hasPrune: argv.includes("--prune"),
+    hasVerbose: argv.includes("--verbose"),
     hasWithEslintMcp: argv.includes("--with-eslint-mcp"),
     hasWrite: argv.includes("--write"),
     maxDurationMs: getNumericFlagValue(argv, "--max-duration"),
@@ -1424,3 +1708,4 @@ export {
   handleUpdate,
   runCli
 };
+//# sourceMappingURL=cli.js.map