@neerav34/env-doctor 1.0.0

package/dist/index.js

@@ -0,0 +1,1017 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command, Option } from "commander";
+
+// src/commands/check.ts
+import path5 from "path";
+import { writeFile, readFile as readFile4 } from "fs/promises";
+
+// src/core/parser.ts
+import { readFile } from "fs/promises";
+async function parseEnvFile(filePath, isExample) {
+  let content;
+  try {
+    content = await readFile(filePath, "utf-8");
+  } catch {
+    return { vars: /* @__PURE__ */ new Map(), exists: false };
+  }
+  return { vars: parseEnvContent(content, filePath, isExample), exists: true };
+}
+function parseEnvContent(content, filePath, isExample) {
+  const vars = /* @__PURE__ */ new Map();
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i] ?? "";
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith("//")) continue;
+    if (line.startsWith("export ")) {
+      line = line.slice(7).trim();
+    }
+    const eqIndex = line.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = line.slice(0, eqIndex).trim();
+    if (!key || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    let rawValue = line.slice(eqIndex + 1);
+    if (rawValue.startsWith('"') && !rawValue.slice(1).includes('"') || rawValue.startsWith("'") && !rawValue.slice(1).includes("'")) {
+      const quote = rawValue[0];
+      let combined = rawValue;
+      while (i + 1 < lines.length) {
+        i++;
+        const nextLine = lines[i] ?? "";
+        combined += "\n" + nextLine;
+        if (nextLine.includes(quote)) break;
+      }
+      rawValue = combined;
+    }
+    const value = extractValue(rawValue);
+    const displayValue = truncateValue(value);
+    vars.set(key, {
+      name: key,
+      file: filePath,
+      line: i + 1,
+      ...displayValue !== void 0 ? { value: displayValue } : {},
+      isExample
+    });
+  }
+  return vars;
+}
+function extractValue(raw) {
+  let value = raw.trim();
+  const firstChar = value[0];
+  if (firstChar !== '"' && firstChar !== "'") {
+    const commentIdx = value.search(/\s+#/);
+    if (commentIdx !== -1) {
+      value = value.slice(0, commentIdx).trim();
+    }
+  }
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    value = value.slice(1, -1);
+  }
+  return value;
+}
+function truncateValue(value) {
+  if (!value) return void 0;
+  if (value.length <= 3) return "***";
+  return value.slice(0, 3) + "***";
+}
+
+// src/core/scanner.ts
+import { open } from "fs/promises";
+import path3 from "path";
+
+// src/utils/glob.ts
+import fg from "fast-glob";
+import path2 from "path";
+
+// src/utils/gitignore.ts
+import { readFile as readFile2 } from "fs/promises";
+import path from "path";
+async function loadGitignorePatterns(root) {
+  const gitignorePath = path.join(root, ".gitignore");
+  try {
+    const content = await readFile2(gitignorePath, "utf-8");
+    return parseGitignorePatterns(content);
+  } catch {
+    return [];
+  }
+}
+function parseGitignorePatterns(content) {
+  return content.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#")).flatMap((pattern) => {
+    if (pattern.startsWith("!")) return [];
+    if (pattern.endsWith("/")) {
+      const dir = pattern.slice(0, -1);
+      return [`**/${dir}/**`, `${dir}/**`];
+    }
+    if (pattern.startsWith("/")) {
+      return [pattern.slice(1), `${pattern.slice(1)}/**`];
+    }
+    if (pattern.includes("/")) {
+      return [pattern];
+    }
+    return [`**/${pattern}`, `**/${pattern}/**`];
+  });
+}
+
+// src/utils/glob.ts
+var ALWAYS_IGNORE = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/coverage/**",
+  "**/.next/**",
+  "**/.nuxt/**",
+  "**/vendor/**",
+  "**/target/**",
+  "**/bin/**",
+  "**/obj/**",
+  "**/.cache/**",
+  "**/__pycache__/**",
+  "**/*.pyc",
+  "**/*.min.js",
+  "**/*.min.css",
+  "**/*.map",
+  "**/*.lock",
+  "**/package-lock.json",
+  "**/yarn.lock",
+  "**/pnpm-lock.yaml",
+  // Exclude .env files from source scanning — they're parsed separately by parser.ts
+  ".env",
+  "**/.env",
+  ".env.*",
+  "**/.env.*"
+];
+async function findSourceFiles(root, options = {}) {
+  const { ignore = [], respectGitignore = true } = options;
+  const gitignorePatterns = respectGitignore ? await loadGitignorePatterns(root) : [];
+  const allIgnore = [...ALWAYS_IGNORE, ...gitignorePatterns, ...ignore];
+  const files = await fg("**/*", {
+    cwd: root,
+    ignore: allIgnore,
+    absolute: false,
+    dot: true,
+    onlyFiles: true,
+    followSymbolicLinks: false
+  });
+  return files.sort();
+}
+function resolveRoot(providedRoot) {
+  if (providedRoot) {
+    return path2.resolve(providedRoot);
+  }
+  return process.cwd();
+}
+
+// src/core/scanner.ts
+async function scanProjectFiles(root, options = {}) {
+  const allFiles = await findSourceFiles(root, options);
+  const results = await Promise.allSettled(
+    allFiles.map((file) => isTextFile(path3.join(root, file)).then((isText) => isText ? file : null))
+  );
+  const textFiles = [];
+  let skippedFiles = 0;
+  for (const result of results) {
+    if (result.status === "fulfilled" && result.value !== null) {
+      textFiles.push(result.value);
+    } else {
+      skippedFiles++;
+    }
+  }
+  return { files: textFiles, skippedFiles };
+}
+async function isTextFile(fullPath) {
+  let fd = null;
+  try {
+    fd = await open(fullPath, "r");
+    const buffer = Buffer.alloc(1024);
+    const { bytesRead } = await fd.read(buffer, 0, 1024, 0);
+    return !buffer.subarray(0, bytesRead).includes(0);
+  } catch {
+    return false;
+  } finally {
+    await fd?.close().catch(() => void 0);
+  }
+}
+
+// src/core/detector.ts
+import { readFile as readFile3 } from "fs/promises";
+import path4 from "path";
+var PATTERN_DEFS = [
+  // JavaScript / TypeScript — process.env.VAR (dot notation)
+  {
+    lang: "js",
+    source: String.raw`process\.env\.([A-Z_][A-Z0-9_]*)`
+  },
+  // JavaScript / TypeScript — process.env['VAR'] or process.env["VAR"] (bracket notation)
+  {
+    lang: "js",
+    source: String.raw`process\.env\[['"]([A-Z_][A-Z0-9_]*)['"]\]`
+  },
+  // Vite / import.meta.env.VAR
+  {
+    lang: "js",
+    source: String.raw`import\.meta\.env\.([A-Z_][A-Z0-9_]*)`
+  },
+  // Python — os.environ.get('VAR') and os.getenv('VAR') (function call)
+  {
+    lang: "py",
+    source: String.raw`os\.(?:environ\.get|getenv)\(\s*['"]([A-Z_][A-Z0-9_]*)['"]\s*`,
+    extensions: [".py"]
+  },
+  // Python — os.environ['VAR'] (direct subscript)
+  {
+    lang: "py",
+    source: String.raw`os\.environ\[['"]([A-Z_][A-Z0-9_]*)['"]\]`,
+    extensions: [".py"]
+  },
+  // Go — os.Getenv("VAR")
+  {
+    lang: "go",
+    source: String.raw`os\.Getenv\(\s*"([A-Z_][A-Z0-9_]*)"\s*\)`,
+    extensions: [".go"]
+  },
+  // Rust — env::var("VAR") or std::env::var("VAR")
+  {
+    lang: "rs",
+    source: String.raw`env::var\(\s*"([A-Z_][A-Z0-9_]*)"\s*\)`,
+    extensions: [".rs"]
+  },
+  // Ruby — ENV['VAR'] or ENV["VAR"]
+  {
+    lang: "rb",
+    source: String.raw`ENV\[['"]([A-Z_][A-Z0-9_]*)['"]\]`,
+    extensions: [".rb"]
+  },
+  // PHP — $_ENV['VAR'] or $_ENV["VAR"] (array subscript)
+  {
+    lang: "php",
+    source: String.raw`\$_ENV\[['"]([A-Z_][A-Z0-9_]*)['"]\]`,
+    extensions: [".php"]
+  },
+  // PHP — getenv('VAR') (function call)
+  {
+    lang: "php",
+    source: String.raw`getenv\(\s*['"]([A-Z_][A-Z0-9_]*)['"]\s*\)`,
+    extensions: [".php"]
+  },
+  // Docker Compose / Shell — ${VAR} syntax (restrict to avoid false positives)
+  {
+    lang: "sh",
+    source: String.raw`\$\{([A-Z_][A-Z0-9_]*)\}`,
+    extensions: [
+      ".sh",
+      ".bash",
+      ".zsh",
+      ".fish",
+      "Dockerfile",
+      ".dockerfile",
+      "docker-compose.yml",
+      "docker-compose.yaml",
+      ".env.example"
+    ]
+  },
+  // Shell — $VAR syntax (only in shell scripts)
+  {
+    lang: "sh",
+    source: String.raw`(?<![A-Za-z0-9_])\$([A-Z_][A-Z0-9_]*)(?![A-Za-z0-9_({])`,
+    extensions: [".sh", ".bash", ".zsh"]
+  }
+];
+function getLineColumn(content, index) {
+  const before = content.slice(0, index);
+  const lines = before.split("\n");
+  const lastLine = lines[lines.length - 1] ?? "";
+  return {
+    line: lines.length,
+    column: lastLine.length + 1
+  };
+}
+function isCommentedLine(line) {
+  const trimmed = line.trimStart();
+  return trimmed.startsWith("//") || trimmed.startsWith("#") || trimmed.startsWith("*") || trimmed.startsWith("/*") || trimmed.startsWith("--") || trimmed.startsWith("<!--");
+}
+function fileMatchesPattern(filePath, extensions) {
+  const ext = path4.extname(filePath).toLowerCase();
+  const basename = path4.basename(filePath);
+  return extensions.some((e) => ext === e || basename === e || basename.endsWith(e));
+}
+function detectVarsInContent(content, filePath) {
+  const lines = content.split("\n");
+  const seen = /* @__PURE__ */ new Set();
+  const refs = [];
+  for (const def of PATTERN_DEFS) {
+    if (def.extensions && !fileMatchesPattern(filePath, def.extensions)) continue;
+    const regex = new RegExp(def.source, "g");
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const varName = match[1];
+      if (!varName) continue;
+      const pos = getLineColumn(content, match.index);
+      const lineContent = lines[pos.line - 1] ?? "";
+      if (isCommentedLine(lineContent)) continue;
+      const key = `${varName}:${pos.line}:${pos.column}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      refs.push({
+        name: varName,
+        file: filePath,
+        line: pos.line,
+        column: pos.column,
+        pattern: def.lang,
+        context: lineContent.trim()
+      });
+    }
+  }
+  return refs;
+}
+async function detectVarsInFile(root, relativePath) {
+  const fullPath = path4.join(root, relativePath);
+  const content = await readFile3(fullPath, "utf-8");
+  return detectVarsInContent(content, relativePath);
+}
+
+// src/core/analyzer.ts
+function analyze(input) {
+  const { foundVars, envVars, exampleVars } = input;
+  const issues = [];
+  for (const [name, refs] of foundVars) {
+    const inEnv = envVars.has(name);
+    const inExample = exampleVars.has(name);
+    if (!inEnv && !inExample) {
+      issues.push({
+        severity: "error",
+        type: "missing",
+        variable: name,
+        message: `${name} is referenced in ${refs.length} location(s) but not defined in .env or .env.example`,
+        references: refs,
+        suggestion: `Add ${name} to .env.example`
+      });
+    } else if (!inEnv && inExample) {
+      const def = exampleVars.get(name);
+      issues.push({
+        severity: "warn",
+        type: "missing",
+        variable: name,
+        message: `${name} is referenced but missing from .env (documented in .env.example)`,
+        references: refs,
+        ...def !== void 0 ? { definition: def } : {},
+        suggestion: `Copy ${name} from .env.example to .env and set a real value`
+      });
+    }
+  }
+  for (const [name, def] of envVars) {
+    if (!foundVars.has(name)) {
+      issues.push({
+        severity: "warn",
+        type: "unused",
+        variable: name,
+        message: `${name} is defined in .env but never referenced in source code`,
+        definition: def,
+        suggestion: `Remove ${name} from .env, or check for typos in variable name`
+      });
+    }
+    if (!exampleVars.has(name)) {
+      issues.push({
+        severity: "warn",
+        type: "example-drift",
+        variable: name,
+        message: `${name} exists in .env but is missing from .env.example`,
+        definition: def,
+        suggestion: `Run \`env-doctor check --fix\` to sync .env.example`
+      });
+    }
+  }
+  for (const [name, def] of exampleVars) {
+    if (!foundVars.has(name) && !envVars.has(name)) {
+      issues.push({
+        severity: "warn",
+        type: "example-drift",
+        variable: name,
+        message: `${name} is in .env.example but not referenced in code or .env`,
+        definition: def,
+        suggestion: `Remove ${name} from .env.example if it is no longer needed`
+      });
+    }
+  }
+  return issues.sort((a, b) => {
+    if (a.severity !== b.severity) {
+      return a.severity === "error" ? -1 : 1;
+    }
+    return a.variable.localeCompare(b.variable);
+  });
+}
+
+// src/utils/logger.ts
+import chalk from "chalk";
+var colorEnabled = true;
+function setColorEnabled(enabled) {
+  colorEnabled = enabled;
+}
+function c(colorFn, msg) {
+  return colorEnabled ? colorFn(msg) : msg;
+}
+var logger = {
+  error: (msg) => {
+    process.stderr.write(c(chalk.red, msg) + "\n");
+  },
+  warn: (msg) => {
+    process.stderr.write(c(chalk.yellow, msg) + "\n");
+  },
+  info: (msg) => {
+    console.log(c(chalk.blue, msg));
+  },
+  success: (msg) => {
+    console.log(c(chalk.green, msg));
+  },
+  header: (msg) => {
+    console.log(c(chalk.bold.white, msg));
+  },
+  dim: (msg) => {
+    console.log(c(chalk.dim, msg));
+  },
+  log: (msg) => {
+    console.log(msg);
+  },
+  red: (msg) => c(chalk.red, msg),
+  yellow: (msg) => c(chalk.yellow, msg),
+  green: (msg) => c(chalk.green, msg),
+  blue: (msg) => c(chalk.blue, msg),
+  cyan: (msg) => c(chalk.cyan, msg),
+  bold: (msg) => c(chalk.bold, msg),
+  dim_: (msg) => c(chalk.dim, msg),
+  gray: (msg) => c(chalk.gray, msg)
+};
+
+// src/core/reporter.ts
+function reportPretty(result) {
+  const { issues, scannedFiles, skippedFiles, duration } = result;
+  const errors = issues.filter((i) => i.severity === "error");
+  const warns = issues.filter((i) => i.severity === "warn");
+  console.log("");
+  if (errors.length === 0 && warns.length === 0) {
+    logger.success(`  \u2713  All environment variables are properly configured`);
+    printStats(scannedFiles, skippedFiles, duration);
+    return;
+  }
+  if (errors.length > 0) {
+    console.log(logger.bold(logger.red(`  ERRORS (${errors.length})`)));
+    console.log("");
+    for (const issue of errors) {
+      printIssuePretty(issue, "error");
+    }
+  }
+  if (warns.length > 0) {
+    console.log(logger.bold(logger.yellow(`  WARNINGS (${warns.length})`)));
+    console.log("");
+    for (const issue of warns) {
+      printIssuePretty(issue, "warn");
+    }
+  }
+  printStats(scannedFiles, skippedFiles, duration);
+}
+function printIssuePretty(issue, level) {
+  const icon = level === "error" ? logger.red("  \u2717") : logger.yellow("  \u26A0");
+  const typeLbl = formatIssueType(issue.type);
+  const varName = level === "error" ? logger.bold(logger.red(issue.variable)) : logger.bold(logger.yellow(issue.variable));
+  console.log(`${icon}  ${varName}  ${logger.gray(`[${typeLbl}]`)}`);
+  console.log(`     ${logger.gray(issue.message)}`);
+  if (issue.references) {
+    for (const ref of issue.references.slice(0, 3)) {
+      console.log(`     ${logger.dim_("\u2514\u2500")} ${logger.cyan(`${ref.file}:${ref.line}`)}  ${logger.dim_(ref.context)}`);
+    }
+    if (issue.references.length > 3) {
+      console.log(`     ${logger.dim_(`   ... and ${issue.references.length - 3} more`)}`);
+    }
+  }
+  if (issue.definition) {
+    const loc = `${issue.definition.file}:${issue.definition.line}`;
+    console.log(`     ${logger.dim_("\u2514\u2500")} ${logger.cyan(loc)}`);
+  }
+  if (issue.suggestion) {
+    console.log(`     ${logger.green("\u2192")} ${issue.suggestion}`);
+  }
+  console.log("");
+}
+function printStats(scannedFiles, skippedFiles, duration) {
+  console.log("");
+  console.log(
+    logger.dim_(
+      `  Scanned ${scannedFiles} files` + (skippedFiles > 0 ? ` (${skippedFiles} skipped)` : "") + ` in ${duration}ms`
+    )
+  );
+  console.log("");
+}
+function formatIssueType(type) {
+  const labels = {
+    missing: "Missing Required",
+    unused: "Unused Variable",
+    "example-drift": "Example Drift",
+    "type-mismatch": "Type Mismatch"
+  };
+  return labels[type] ?? type;
+}
+function buildJsonOutput(result) {
+  return {
+    success: result.issues.filter((i) => i.severity === "error").length === 0,
+    summary: {
+      errors: result.issues.filter((i) => i.severity === "error").length,
+      warnings: result.issues.filter((i) => i.severity === "warn").length,
+      scannedFiles: result.scannedFiles,
+      skippedFiles: result.skippedFiles,
+      duration: result.duration
+    },
+    issues: result.issues.map((issue) => ({
+      severity: issue.severity,
+      type: issue.type,
+      variable: issue.variable,
+      message: issue.message,
+      ...issue.references !== void 0 ? { references: issue.references.map((r) => ({ file: r.file, line: r.line, column: r.column, context: r.context })) } : {},
+      ...issue.definition !== void 0 ? { definition: { file: issue.definition.file, line: issue.definition.line } } : {},
+      ...issue.suggestion !== void 0 ? { suggestion: issue.suggestion } : {}
+    }))
+  };
+}
+function reportJson(result) {
+  console.log(JSON.stringify(buildJsonOutput(result), null, 2));
+}
+function reportMarkdown(result) {
+  const { issues, scannedFiles, duration } = result;
+  const errors = issues.filter((i) => i.severity === "error");
+  const warns = issues.filter((i) => i.severity === "warn");
+  const lines = [];
+  lines.push("## Environment Variable Report");
+  lines.push("");
+  if (errors.length === 0 && warns.length === 0) {
+    lines.push("\u2705 All environment variables are properly configured.");
+  } else {
+    const badge = errors.length > 0 ? "\u{1F534}" : "\u{1F7E1}";
+    lines.push(`${badge} **${errors.length} error(s), ${warns.length} warning(s)**`);
+    lines.push("");
+    if (errors.length > 0) {
+      lines.push("### Errors");
+      lines.push("");
+      for (const issue of errors) {
+        lines.push(issueToMarkdown(issue));
+      }
+    }
+    if (warns.length > 0) {
+      lines.push("### Warnings");
+      lines.push("");
+      for (const issue of warns) {
+        lines.push(issueToMarkdown(issue));
+      }
+    }
+  }
+  lines.push("---");
+  lines.push(`_Scanned ${scannedFiles} files in ${duration}ms_`);
+  console.log(lines.join("\n"));
+}
+function issueToMarkdown(issue) {
+  const parts = [];
+  const icon = issue.severity === "error" ? "\u274C" : "\u26A0\uFE0F";
+  parts.push(`#### ${icon} \`${issue.variable}\``);
+  parts.push("");
+  parts.push(issue.message);
+  if (issue.references && issue.references.length > 0) {
+    parts.push("");
+    parts.push("**References:**");
+    for (const ref of issue.references) {
+      parts.push(`- \`${ref.file}:${ref.line}\` \u2014 \`${ref.context}\``);
+    }
+  }
+  if (issue.suggestion) {
+    parts.push("");
+    parts.push(`> \u{1F4A1} ${issue.suggestion}`);
+  }
+  parts.push("");
+  return parts.join("\n");
+}
+function reportDoctor(result, health) {
+  const scoreColor = health.score >= 80 ? logger.green : health.score >= 50 ? logger.yellow : logger.red;
+  const scoreIcon = health.score >= 80 ? "\u2713" : health.score >= 50 ? "\u26A0" : "\u2717";
+  console.log("");
+  console.log(logger.bold("  ENVIRONMENT HEALTH REPORT"));
+  console.log("");
+  console.log(`  Health Score: ${scoreColor(`${health.score}/100`)} ${scoreIcon}`);
+  console.log("");
+  if (health.breakdown.length > 0) {
+    console.log(logger.bold("  Breakdown:"));
+    for (const item of health.breakdown) {
+      const pts = item.points > 0 ? logger.red(`-${item.points} pts`) : logger.green("0 pts");
+      console.log(`    ${item.label.padEnd(25)} ${String(item.count).padStart(3)}  (${pts})`);
+    }
+    console.log("");
+  }
+  if (health.mostProblematicFiles.length > 0) {
+    console.log(logger.bold("  Most Problematic Files:"));
+    health.mostProblematicFiles.forEach((f, idx) => {
+      console.log(`    ${idx + 1}. ${logger.cyan(f.file)}  ${logger.gray(`(${f.issueCount} issue${f.issueCount === 1 ? "" : "s"})`)}`);
+    });
+    console.log("");
+  }
+  if (health.recommendations.length > 0) {
+    console.log(logger.bold("  Recommendations:"));
+    for (const rec of health.recommendations) {
+      console.log(`    ${logger.green("\u2192")} ${rec}`);
+    }
+    console.log("");
+  }
+  reportPretty(result);
+}
+
+// src/commands/check.ts
+async function runCheck(options) {
+  const { format, noColor, strict, fix } = options;
+  setColorEnabled(!noColor);
+  const root = resolveRoot(options.root);
+  const envFilePath = path5.resolve(root, options.envFile);
+  const exampleFilePath = path5.resolve(root, options.exampleFile);
+  const start = Date.now();
+  const [envResult, exampleResult] = await Promise.all([
+    parseEnvFile(envFilePath, false),
+    parseEnvFile(exampleFilePath, true)
+  ]);
+  const { files, skippedFiles } = await scanProjectFiles(root, {
+    ignore: options.ignore,
+    respectGitignore: true
+  });
+  const refResults = await Promise.allSettled(
+    files.map((file) => detectVarsInFile(root, file))
+  );
+  const foundVars = /* @__PURE__ */ new Map();
+  for (const result of refResults) {
+    if (result.status !== "fulfilled") continue;
+    for (const ref of result.value) {
+      const existing = foundVars.get(ref.name) ?? [];
+      existing.push(ref);
+      foundVars.set(ref.name, existing);
+    }
+  }
+  const issues = analyze({
+    foundVars,
+    envVars: envResult.vars,
+    exampleVars: exampleResult.vars
+  });
+  const duration = Date.now() - start;
+  const scanResult = {
+    projectRoot: root,
+    scannedFiles: files.length,
+    skippedFiles,
+    foundVars,
+    envVars: envResult.vars,
+    exampleVars: exampleResult.vars,
+    issues,
+    duration
+  };
+  if (fix) {
+    await applyFix(scanResult, exampleFilePath);
+  }
+  switch (format) {
+    case "json":
+      reportJson(scanResult);
+      break;
+    case "markdown":
+      reportMarkdown(scanResult);
+      break;
+    default:
+      reportPretty(scanResult);
+  }
+  const hasErrors = issues.some((i) => i.severity === "error");
+  const hasWarns = issues.some((i) => i.severity === "warn");
+  if (hasErrors || strict && hasWarns) {
+    process.exit(1);
+  } else if (hasWarns) {
+    process.exit(2);
+  } else {
+    process.exit(0);
+  }
+}
+async function applyFix(result, exampleFilePath) {
+  const { foundVars, exampleVars } = result;
+  const newVars = [];
+  for (const [name] of foundVars) {
+    if (!exampleVars.has(name)) {
+      newVars.push(name);
+    }
+  }
+  if (newVars.length === 0) return;
+  let existing = "";
+  try {
+    existing = await readFile4(exampleFilePath, "utf-8");
+  } catch {
+  }
+  const additions = newVars.sort().map((name) => {
+    const refs = result.foundVars.get(name) ?? [];
+    const firstRef = refs[0];
+    const comment = firstRef ? ` # referenced in ${firstRef.file}:${firstRef.line}` : "";
+    return `${name}=${comment}`;
+  }).join("\n");
+  const newContent = existing ? existing.trimEnd() + "\n\n# Added by env-doctor check --fix\n" + additions + "\n" : additions + "\n";
+  await writeFile(exampleFilePath, newContent, "utf-8");
+  console.log(`
+  Fixed: added ${newVars.length} variable(s) to ${result.exampleVars.size > 0 ? exampleFilePath : ".env.example"}`);
+}
+
+// src/commands/init.ts
+import path6 from "path";
+import { writeFile as writeFile2, readFile as readFile5 } from "fs/promises";
+async function runInit(options) {
+  setColorEnabled(!options.noColor);
+  const root = resolveRoot(options.root);
+  const envFilePath = path6.resolve(root, options.envFile);
+  const exampleFilePath = path6.resolve(root, options.exampleFile);
+  logger.header("\n  Generating .env.example...\n");
+  const start = Date.now();
+  const [envResult, existingExampleResult] = await Promise.all([
+    parseEnvFile(envFilePath, false),
+    parseEnvFile(exampleFilePath, true)
+  ]);
+  const { files } = await scanProjectFiles(root, {
+    ignore: options.ignore,
+    respectGitignore: true
+  });
+  const refResults = await Promise.allSettled(
+    files.map((file) => detectVarsInFile(root, file))
+  );
+  const foundVarsMap = /* @__PURE__ */ new Map();
+  for (const result of refResults) {
+    if (result.status !== "fulfilled") continue;
+    for (const ref of result.value) {
+      if (!foundVarsMap.has(ref.name)) {
+        foundVarsMap.set(ref.name, ref);
+      }
+    }
+  }
+  const allVarNames = /* @__PURE__ */ new Set([
+    ...foundVarsMap.keys(),
+    ...envResult.vars.keys()
+  ]);
+  const existingNames = new Set(existingExampleResult.vars.keys());
+  const newVars = [];
+  const presentVars = [];
+  for (const name of allVarNames) {
+    if (existingNames.has(name)) {
+      presentVars.push(name);
+    } else {
+      newVars.push(name);
+    }
+  }
+  if (newVars.length === 0 && existingExampleResult.exists) {
+    logger.success(`  \u2713  .env.example is already up to date (${presentVars.length} variable${presentVars.length === 1 ? "" : "s"})
+`);
+    return;
+  }
+  const content = buildExampleContent({
+    existingContent: existingExampleResult.exists ? await readFile5(exampleFilePath, "utf-8").catch(() => "") : null,
+    newVars,
+    presentVars,
+    foundVarsMap,
+    envVars: envResult.vars,
+    withComments: options.withComments
+  });
+  await writeFile2(exampleFilePath, content, "utf-8");
+  const duration = Date.now() - start;
+  logger.success(
+    `  \u2713  ${existingExampleResult.exists ? "Updated" : "Created"} ${options.exampleFile} with ${allVarNames.size} variable${allVarNames.size === 1 ? "" : "s"} (${newVars.length} new, ${presentVars.length} already present)
+`
+  );
+  if (newVars.length > 0) {
+    logger.bold("  New variables added:");
+    for (const name of newVars.sort()) {
+      const ref = foundVarsMap.get(name);
+      const loc = ref ? logger.dim_(`  # from ${ref.file}:${ref.line}`) : "";
+      logger.log(`    ${logger.cyan(name)}${loc}`);
+    }
+  }
+  logger.dim_(`
+  Completed in ${duration}ms
+`);
+}
+function buildExampleContent(opts) {
+  const { existingContent, newVars, foundVarsMap, envVars, withComments } = opts;
+  if (existingContent !== null && newVars.length > 0) {
+    const additions = newVars.sort().map((name) => formatVar(name, foundVarsMap.get(name), envVars, withComments)).join("\n");
+    return existingContent.trimEnd() + "\n\n# Added by env-doctor init\n" + additions + "\n";
+  }
+  const allNames = [.../* @__PURE__ */ new Set([...foundVarsMap.keys(), ...envVars.keys()])].sort();
+  const lines = [
+    "# Environment Variables",
+    "# Generated by env-doctor init \u2014 do not commit real values",
+    ""
+  ];
+  for (const name of allNames) {
+    lines.push(formatVar(name, foundVarsMap.get(name), envVars, withComments));
+  }
+  return lines.join("\n") + "\n";
+}
+function formatVar(name, ref, envVars, withComments) {
+  const def = envVars.get(name);
+  const placeholder = def?.value ? `# ${def.value}` : "";
+  const comment = withComments && ref ? `  # referenced in ${ref.file}:${ref.line}` : "";
+  return `${name}=${placeholder}${comment}`;
+}
+
+// src/commands/doctor.ts
+import path7 from "path";
+import { readFile as readFile6, writeFile as writeFile3, mkdir } from "fs/promises";
+var SEVERITY_POINTS = { error: 10, warn: 3, info: 0 };
+var CACHE_DIR = ".env-doctor";
+var CACHE_FILE = "cache.json";
+async function runDoctor(options) {
+  setColorEnabled(!options.noColor);
+  const root = resolveRoot(options.root);
+  const envFilePath = path7.resolve(root, options.envFile);
+  const exampleFilePath = path7.resolve(root, options.exampleFile);
+  const start = Date.now();
+  const [envResult, exampleResult] = await Promise.all([
+    parseEnvFile(envFilePath, false),
+    parseEnvFile(exampleFilePath, true)
+  ]);
+  const { files, skippedFiles } = await scanProjectFiles(root, {
+    ignore: options.ignore,
+    respectGitignore: true
+  });
+  const refResults = await Promise.allSettled(
+    files.map((file) => detectVarsInFile(root, file))
+  );
+  const foundVars = /* @__PURE__ */ new Map();
+  for (const result of refResults) {
+    if (result.status !== "fulfilled") continue;
+    for (const ref of result.value) {
+      const existing = foundVars.get(ref.name) ?? [];
+      existing.push(ref);
+      foundVars.set(ref.name, existing);
+    }
+  }
+  const issues = analyze({
+    foundVars,
+    envVars: envResult.vars,
+    exampleVars: exampleResult.vars
+  });
+  const duration = Date.now() - start;
+  const scanResult = {
+    projectRoot: root,
+    scannedFiles: files.length,
+    skippedFiles,
+    foundVars,
+    envVars: envResult.vars,
+    exampleVars: exampleResult.vars,
+    issues,
+    duration
+  };
+  const health = buildHealthReport(scanResult);
+  const previous = await loadCache(root);
+  if (previous) {
+    const delta = health.score - previous.healthScore;
+    const trend = delta > 0 ? `+${delta}` : String(delta);
+    const arrow = delta > 0 ? "\u2191" : delta < 0 ? "\u2193" : "\u2192";
+    console.log(`
+  Trend: ${arrow} ${trend} pts from last scan (${previous.timestamp})`);
+  }
+  await saveCache(root, health);
+  reportDoctor(scanResult, health);
+  const hasErrors = issues.some((i) => i.severity === "error");
+  const hasWarns = issues.some((i) => i.severity === "warn");
+  if (hasErrors || options.strict && hasWarns) {
+    process.exit(1);
+  } else if (hasWarns) {
+    process.exit(2);
+  }
+}
+function buildHealthReport(result) {
+  const { issues } = result;
+  const errorCount = issues.filter((i) => i.severity === "error").length;
+  const warnCount = issues.filter((i) => i.severity === "warn").length;
+  const totalPoints = errorCount * SEVERITY_POINTS.error + warnCount * SEVERITY_POINTS.warn;
+  const score = Math.max(0, 100 - totalPoints);
+  const typeCounts = {};
+  for (const issue of issues) {
+    typeCounts[issue.type] = (typeCounts[issue.type] ?? 0) + 1;
+  }
+  const breakdown = Object.entries(typeCounts).map(([type, count]) => {
+    const pts = issues.filter((i) => i.type === type).reduce((sum, i) => sum + SEVERITY_POINTS[i.severity], 0);
+    return {
+      label: formatTypeLabel(type),
+      count,
+      points: pts
+    };
+  });
+  const fileCounts = /* @__PURE__ */ new Map();
+  for (const issue of issues) {
+    for (const ref of issue.references ?? []) {
+      fileCounts.set(ref.file, (fileCounts.get(ref.file) ?? 0) + 1);
+    }
+  }
+  const mostProblematicFiles = [...fileCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([file, issueCount]) => ({ file, issueCount }));
+  const recommendations = [];
+  if (issues.some((i) => i.type === "missing" && i.severity === "error")) {
+    recommendations.push("Run `env-doctor check --fix` to update .env.example");
+  }
+  const unusedVars = issues.filter((i) => i.type === "unused").map((i) => i.variable);
+  if (unusedVars.length > 0) {
+    const list = unusedVars.slice(0, 3).join(", ");
+    const more = unusedVars.length > 3 ? ` (+${unusedVars.length - 3} more)` : "";
+    recommendations.push(`Review unused variables: ${list}${more}`);
+  }
+  if (issues.some((i) => i.type === "example-drift")) {
+    recommendations.push("Run `env-doctor init` to regenerate .env.example from current code");
+  }
+  return {
+    score,
+    errorCount,
+    warnCount,
+    breakdown,
+    mostProblematicFiles,
+    recommendations
+  };
+}
+function formatTypeLabel(type) {
+  const labels = {
+    missing: "Missing Required",
+    unused: "Unused Variables",
+    "example-drift": "Example Drift",
+    "type-mismatch": "Type Mismatches"
+  };
+  return labels[type] ?? type;
+}
+async function loadCache(root) {
+  const cachePath = path7.join(root, CACHE_DIR, CACHE_FILE);
+  try {
+    const raw = await readFile6(cachePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function saveCache(root, health) {
+  const cacheDir = path7.join(root, CACHE_DIR);
+  const cachePath = path7.join(cacheDir, CACHE_FILE);
+  try {
+    await mkdir(cacheDir, { recursive: true });
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      healthScore: health.score,
+      errorCount: health.errorCount,
+      warnCount: health.warnCount
+    };
+    await writeFile3(cachePath, JSON.stringify(entry, null, 2), "utf-8");
+  } catch {
+  }
+}
+
+// src/index.ts
+var DEFAULT_IGNORE = ["node_modules", "dist", ".git"];
+var program = new Command();
+program.name("env-doctor").description("The eslint of environment variables \u2014 catch missing env vars before they hit production").version("1.0.0");
+program.command("check").description("Scan codebase and report environment variable discrepancies").option("--fix", "Auto-update .env.example to match code references", false).option("--strict", "Treat warnings as errors (exit 1)", false).option("--env-file <path>", "Path to .env file", ".env").option("--example-file <path>", "Path to .env.example file", ".env.example").option("--ignore <patterns...>", "Additional glob patterns to skip", DEFAULT_IGNORE).option("--no-color", "Disable ANSI color output").option("--root <path>", "Project root directory (default: cwd)").addOption(
+  new Option("--format <format>", "Output format").choices(["pretty", "json", "markdown"]).default("pretty")
+).action(async (opts) => {
+  const options = {
+    fix: Boolean(opts["fix"]),
+    strict: Boolean(opts["strict"]),
+    envFile: String(opts["envFile"] ?? ".env"),
+    exampleFile: String(opts["exampleFile"] ?? ".env.example"),
+    ignore: Array.isArray(opts["ignore"]) ? opts["ignore"] : DEFAULT_IGNORE,
+    format: opts["format"] ?? "pretty",
+    noColor: !opts["color"],
+    root: String(opts["root"] ?? "")
+  };
+  await runCheck(options).catch(fatalError);
+});
+program.command("init").description("Generate or update .env.example from code references and .env").option("--env-file <path>", "Path to .env file", ".env").option("--example-file <path>", "Path to .env.example file", ".env.example").option("--ignore <patterns...>", "Additional glob patterns to skip", DEFAULT_IGNORE).option("--with-comments", "Add source file comments to each variable", false).option("--no-color", "Disable ANSI color output").option("--root <path>", "Project root directory (default: cwd)").action(async (opts) => {
+  const options = {
+    envFile: String(opts["envFile"] ?? ".env"),
+    exampleFile: String(opts["exampleFile"] ?? ".env.example"),
+    ignore: Array.isArray(opts["ignore"]) ? opts["ignore"] : DEFAULT_IGNORE,
+    withComments: Boolean(opts["withComments"]),
+    noColor: !opts["color"],
+    root: String(opts["root"] ?? "")
+  };
+  await runInit(options).catch(fatalError);
+});
+program.command("doctor").description("Full diagnostic with health score and trend analysis").option("--strict", "Treat warnings as errors (exit 1)", false).option("--env-file <path>", "Path to .env file", ".env").option("--example-file <path>", "Path to .env.example file", ".env.example").option("--ignore <patterns...>", "Additional glob patterns to skip", DEFAULT_IGNORE).option("--no-color", "Disable ANSI color output").option("--root <path>", "Project root directory (default: cwd)").addOption(
+  new Option("--format <format>", "Output format").choices(["pretty", "json", "markdown"]).default("pretty")
+).action(async (opts) => {
+  const options = {
+    fix: false,
+    strict: Boolean(opts["strict"]),
+    envFile: String(opts["envFile"] ?? ".env"),
+    exampleFile: String(opts["exampleFile"] ?? ".env.example"),
+    ignore: Array.isArray(opts["ignore"]) ? opts["ignore"] : DEFAULT_IGNORE,
+    format: opts["format"] ?? "pretty",
+    noColor: !opts["color"],
+    root: String(opts["root"] ?? "")
+  };
+  await runDoctor(options).catch(fatalError);
+});
+function fatalError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`
+  Fatal error: ${message}
+
+`);
+  process.exit(3);
+}
+program.parseAsync(process.argv).catch(fatalError);
+//# sourceMappingURL=index.js.map