env-example-doctor 0.0.0-stage → 1.0.0

package/dist/cli.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import path3 from "path";
+import { parseArgs } from "util";
+
+// src/env-file.ts
+function parseEnvExample(content) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    const key = (eq === -1 ? trimmed : trimmed.slice(0, eq)).trim();
+    if (/^[A-Z_][A-Z0-9_]*$/.test(key)) keys.add(key);
+  }
+  return keys;
+}
+function formatEnvExampleAppend(keys) {
+  if (keys.length === 0) return "";
+  const body = keys.map((k) => `${k}=
+`).join("");
+  return `
+# suggested by env-doctor
+${body}`;
+}
+
+// src/analyze.ts
+import { access, readFile as readFile2 } from "fs/promises";
+import path2 from "path";
+
+// src/scan.ts
+var ENV_DOT_RX = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+var META_DOT_RX = /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/g;
+var ENV_BRACKET_RX = /process\.env\[['"]([A-Z_][A-Z0-9_]*)['"]\]/g;
+var META_BRACKET_RX = /import\.meta\.env\[['"]([A-Z_][A-Z0-9_]*)['"]\]/g;
+var ENV_DESTRUCT_RX = /\{\s*([^}]+)\s*\}\s*=\s*process\.env\b/g;
+var KEY_RX = /^[A-Z_][A-Z0-9_]*$/;
+function collectMatches(text, rx, found) {
+  rx.lastIndex = 0;
+  let m;
+  while ((m = rx.exec(text)) !== null) {
+    if (m[1]) found.add(m[1]);
+  }
+}
+function collectDestructured(text, found) {
+  ENV_DESTRUCT_RX.lastIndex = 0;
+  let m;
+  while ((m = ENV_DESTRUCT_RX.exec(text)) !== null) {
+    const inner = m[1];
+    if (!inner) continue;
+    for (const part of inner.split(",")) {
+      const trimmed = part.trim();
+      if (!trimmed) continue;
+      const head = trimmed.split(/\s*[=:]/)[0]?.trim() ?? "";
+      const name = head.replace(/^\.\.\./, "").trim();
+      if (KEY_RX.test(name)) found.add(name);
+    }
+  }
+}
+function scanSourceForEnv(text) {
+  const found = /* @__PURE__ */ new Set();
+  for (const rx of [ENV_DOT_RX, META_DOT_RX, ENV_BRACKET_RX, META_BRACKET_RX]) {
+    collectMatches(text, rx, found);
+  }
+  collectDestructured(text, found);
+  return found;
+}
+
+// src/walk.ts
+import { readdir, readFile, stat } from "fs/promises";
+import path from "path";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "coverage", ".turbo"]);
+var SOURCE_EXT = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte"]);
+function pathIgnored(rel, patterns) {
+  const norm = rel.replace(/\\/g, "/");
+  return patterns.some((pat) => {
+    if (pat.includes("*")) {
+      const re = new RegExp(
+        "^" + pat.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\?/g, ".") + "$"
+      );
+      return re.test(norm);
+    }
+    return norm.includes(pat.replace(/\\/g, "/"));
+  });
+}
+async function listSourceFiles(root, ignore = []) {
+  const out = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      const rel = path.relative(root, full);
+      if (pathIgnored(rel, ignore)) continue;
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) continue;
+        await walk(full);
+      } else if (ent.isFile()) {
+        const ext = path.extname(ent.name);
+        if (SOURCE_EXT.has(ext)) out.push(full);
+      }
+    }
+  }
+  const st = await stat(root);
+  if (!st.isDirectory()) return out;
+  await walk(root);
+  return out;
+}
+async function readSources(paths) {
+  const map = /* @__PURE__ */ new Map();
+  await Promise.all(
+    paths.map(async (p) => {
+      const text = await readFile(p, "utf8");
+      map.set(p, text);
+    })
+  );
+  return map;
+}
+
+// src/analyze.ts
+async function analyzeEnv(options = {}) {
+  const root = path2.resolve(options.root ?? process.cwd());
+  const envPath = path2.resolve(options.envExamplePath ?? path2.join(root, ".env.example"));
+  const ignore = options.ignore ?? [];
+  let documented = /* @__PURE__ */ new Set();
+  let envExampleFound = false;
+  try {
+    await access(envPath);
+    envExampleFound = true;
+    const example = await readFile2(envPath, "utf8");
+    documented = parseEnvExample(example);
+  } catch {
+    documented = /* @__PURE__ */ new Set();
+  }
+  const files = await listSourceFiles(root, ignore);
+  const sources = await readSources(files);
+  const used = /* @__PURE__ */ new Set();
+  for (const text of sources.values()) {
+    for (const k of scanSourceForEnv(text)) used.add(k);
+  }
+  const missingInExample = [...used].filter((k) => !documented.has(k)).sort();
+  const unusedInCode = [...documented].filter((k) => !used.has(k)).sort();
+  return {
+    usedInCode: [...used].sort(),
+    documented: [...documented].sort(),
+    missingInExample,
+    unusedInCode,
+    ok: missingInExample.length === 0 && unusedInCode.length === 0,
+    envExamplePath: envPath,
+    envExampleFound
+  };
+}
+function shouldFail(report, failOn) {
+  if (failOn === "missing") return report.missingInExample.length > 0;
+  if (failOn === "unused") return report.unusedInCode.length > 0;
+  return !report.ok;
+}
+
+// src/version.ts
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+function readPackageVersion() {
+  try {
+    const entry = process.argv[1];
+    if (!entry) return "0.0.0";
+    const pkgPath = join(dirname(entry), "..", "package.json");
+    const parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (parsed && typeof parsed === "object" && "version" in parsed) {
+      return parsed.version;
+    }
+  } catch {
+  }
+  return "0.0.0";
+}
+
+// src/cli.ts
+function printHelp() {
+  process.stdout.write(`env-doctor \u2014 sync code env usage with .env.example
+
+Usage:
+  env-doctor [project-dir] [--env-example <file>] [--json] [--ignore <glob>]
+            [--fail-on missing|unused|any] [--suggest]
+
+Options:
+  --env-example    Path to .env.example (default: <dir>/.env.example)
+  --json           JSON report on stdout
+  --suggest        Print lines to append for missing keys (stdout only)
+  --ignore         Glob to skip (repeatable)
+  --fail-on        CI failure mode (default: any)
+  -h, --help
+  --version
+`);
+}
+function main() {
+  const { values, positionals } = parseArgs({
+    options: {
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      suggest: { type: "boolean", default: false },
+      ignore: { type: "string", multiple: true, default: [] },
+      "env-example": { type: "string" },
+      "fail-on": { type: "string", default: "any" }
+    },
+    allowPositionals: true
+  });
+  if (values.version) {
+    process.stdout.write(`${readPackageVersion()}
+`);
+    return Promise.resolve(0);
+  }
+  if (values.help) {
+    printHelp();
+    return Promise.resolve(0);
+  }
+  const root = path3.resolve(positionals[0] ?? process.cwd());
+  const failOn = values["fail-on"];
+  const envExamplePath = values["env-example"] ? path3.resolve(String(values["env-example"])) : void 0;
+  return analyzeEnv({ root, ignore: values.ignore, envExamplePath }).then((report) => {
+    if (values.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    } else {
+      process.stdout.write(`Env file: ${report.envExamplePath}${report.envExampleFound ? "" : " (not found)"}
+`);
+      process.stdout.write(`Used in code: ${String(report.usedInCode.length)}
+`);
+      process.stdout.write(`In .env.example: ${String(report.documented.length)}
+`);
+      if (report.missingInExample.length) {
+        process.stdout.write(`
+Missing in .env.example:
+`);
+        for (const k of report.missingInExample) process.stdout.write(`  - ${k}
+`);
+      }
+      if (report.unusedInCode.length) {
+        process.stdout.write(`
+Unused in code:
+`);
+        for (const k of report.unusedInCode) process.stdout.write(`  - ${k}
+`);
+      }
+      if (report.ok) process.stdout.write("\nAll env keys are documented and used.\n");
+      if (values.suggest && report.missingInExample.length) {
+        process.stdout.write("\nSuggested append:\n");
+        process.stdout.write(formatEnvExampleAppend(report.missingInExample));
+      }
+    }
+    return shouldFail(report, failOn) ? 1 : 0;
+  });
+}
+main().then((code) => process.exit(code)).catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(2);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/env-file.ts","../src/analyze.ts","../src/scan.ts","../src/walk.ts","../src/version.ts"],"sourcesContent":["#!/usr/bin/env node\nimport path from 'node:path';\nimport { parseArgs } from 'node:util';\nimport { formatEnvExampleAppend } from './env-file.js';\nimport { analyzeEnv, shouldFail, type FailOn } from './index.js';\nimport { readPackageVersion } from './version.js';\n\nfunction printHelp(): void {\n  process.stdout.write(`env-doctor — sync code env usage with .env.example\n\nUsage:\n  env-doctor [project-dir] [--env-example <file>] [--json] [--ignore <glob>]\n            [--fail-on missing|unused|any] [--suggest]\n\nOptions:\n  --env-example    Path to .env.example (default: <dir>/.env.example)\n  --json           JSON report on stdout\n  --suggest        Print lines to append for missing keys (stdout only)\n  --ignore         Glob to skip (repeatable)\n  --fail-on        CI failure mode (default: any)\n  -h, --help\n  --version\n`);\n}\n\nfunction main(): Promise<number> {\n  const { values, positionals } = parseArgs({\n    options: {\n      help: { type: 'boolean', short: 'h', default: false },\n      version: { type: 'boolean', default: false },\n      json: { type: 'boolean', default: false },\n      suggest: { type: 'boolean', default: false },\n      ignore: { type: 'string', multiple: true, default: [] },\n      'env-example': { type: 'string' },\n      'fail-on': { type: 'string', default: 'any' },\n    },\n    allowPositionals: true,\n  });\n\n  if (values.version) {\n    process.stdout.write(`${readPackageVersion()}\\n`);\n    return Promise.resolve(0);\n  }\n  if (values.help) {\n    printHelp();\n    return Promise.resolve(0);\n  }\n\n  const root = path.resolve(positionals[0] ?? process.cwd());\n  const failOn = values['fail-on'] as FailOn;\n\n  const envExamplePath = values['env-example']\n    ? path.resolve(String(values['env-example']))\n  : undefined;\n\n  return analyzeEnv({ root, ignore: values.ignore, envExamplePath }).then((report) => {\n    if (values.json) {\n      process.stdout.write(`${JSON.stringify(report, null, 2)}\\n`);\n    } else {\n      process.stdout.write(`Env file: ${report.envExamplePath}${report.envExampleFound ? '' : ' (not found)'}\\n`);\n      process.stdout.write(`Used in code: ${String(report.usedInCode.length)}\\n`);\n      process.stdout.write(`In .env.example: ${String(report.documented.length)}\\n`);\n      if (report.missingInExample.length) {\n        process.stdout.write(`\\nMissing in .env.example:\\n`);\n        for (const k of report.missingInExample) process.stdout.write(`  - ${k}\\n`);\n      }\n      if (report.unusedInCode.length) {\n        process.stdout.write(`\\nUnused in code:\\n`);\n        for (const k of report.unusedInCode) process.stdout.write(`  - ${k}\\n`);\n      }\n      if (report.ok) process.stdout.write('\\nAll env keys are documented and used.\\n');\n      if (values.suggest && report.missingInExample.length) {\n        process.stdout.write('\\nSuggested append:\\n');\n        process.stdout.write(formatEnvExampleAppend(report.missingInExample));\n      }\n    }\n    return shouldFail(report, failOn) ? 1 : 0;\n  });\n}\n\nmain()\n  .then((code) => process.exit(code))\n  .catch((err: unknown) => {\n    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\\n`);\n    process.exit(2);\n  });\n","/**\n * Parse `.env.example` style files (KEY=value, comments and blanks ignored).\n */\nexport function parseEnvExample(content: string): Set<string> {\n  const keys = new Set<string>();\n  for (const line of content.split(/\\r?\\n/)) {\n    const trimmed = line.trim();\n    if (!trimmed || trimmed.startsWith('#')) continue;\n    const eq = trimmed.indexOf('=');\n    const key = (eq === -1 ? trimmed : trimmed.slice(0, eq)).trim();\n    if (/^[A-Z_][A-Z0-9_]*$/.test(key)) keys.add(key);\n  }\n  return keys;\n}\n\n/** Lines to append when keys are missing from `.env.example`. */\nexport function suggestEnvExampleLines(keys: string[]): string[] {\n  return keys.map((k) => `${k}=`);\n}\n\nexport function formatEnvExampleAppend(keys: string[]): string {\n  if (keys.length === 0) return '';\n  const body = keys.map((k) => `${k}=\\n`).join('');\n  return `\\n# suggested by env-doctor\\n${body}`;\n}\n","import { access, readFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport { parseEnvExample } from './env-file.js';\nimport { scanSourceForEnv } from './scan.js';\nimport { listSourceFiles, readSources } from './walk.js';\n\nexport type FailOn = 'missing' | 'unused' | 'any';\n\nexport interface EnvDoctorOptions {\n  root?: string;\n  envExamplePath?: string;\n  ignore?: string[];\n}\n\nexport interface EnvDoctorReport {\n  usedInCode: string[];\n  documented: string[];\n  missingInExample: string[];\n  unusedInCode: string[];\n  ok: boolean;\n  /** Resolved path to the env example file that was read (or attempted). */\n  envExamplePath: string;\n  /** False when the env example file does not exist (all keys treated as undocumented). */\n  envExampleFound: boolean;\n}\n\n/**\n * Compare env usage in source against `.env.example`.\n */\nexport async function analyzeEnv(options: EnvDoctorOptions = {}): Promise<EnvDoctorReport> {\n  const root = path.resolve(options.root ?? process.cwd());\n  const envPath = path.resolve(options.envExamplePath ?? path.join(root, '.env.example'));\n  const ignore = options.ignore ?? [];\n\n  let documented = new Set<string>();\n  let envExampleFound = false;\n  try {\n    await access(envPath);\n    envExampleFound = true;\n    const example = await readFile(envPath, 'utf8');\n    documented = parseEnvExample(example);\n  } catch {\n    documented = new Set();\n  }\n\n  const files = await listSourceFiles(root, ignore);\n  const sources = await readSources(files);\n  const used = new Set<string>();\n  for (const text of sources.values()) {\n    for (const k of scanSourceForEnv(text)) used.add(k);\n  }\n\n  const missingInExample = [...used].filter((k) => !documented.has(k)).sort();\n  const unusedInCode = [...documented].filter((k) => !used.has(k)).sort();\n\n  return {\n    usedInCode: [...used].sort(),\n    documented: [...documented].sort(),\n    missingInExample,\n    unusedInCode,\n    ok: missingInExample.length === 0 && unusedInCode.length === 0,\n    envExamplePath: envPath,\n    envExampleFound,\n  };\n}\n\nexport function shouldFail(report: EnvDoctorReport, failOn: FailOn): boolean {\n  if (failOn === 'missing') return report.missingInExample.length > 0;\n  if (failOn === 'unused') return report.unusedInCode.length > 0;\n  return !report.ok;\n}\n","const ENV_DOT_RX = /process\\.env\\.([A-Z_][A-Z0-9_]*)/g;\nconst META_DOT_RX = /import\\.meta\\.env\\.([A-Z_][A-Z0-9_]*)/g;\nconst ENV_BRACKET_RX = /process\\.env\\[['\"]([A-Z_][A-Z0-9_]*)['\"]\\]/g;\nconst META_BRACKET_RX = /import\\.meta\\.env\\[['\"]([A-Z_][A-Z0-9_]*)['\"]\\]/g;\nconst ENV_DESTRUCT_RX = /\\{\\s*([^}]+)\\s*\\}\\s*=\\s*process\\.env\\b/g;\n\nconst KEY_RX = /^[A-Z_][A-Z0-9_]*$/;\n\nfunction collectMatches(text: string, rx: RegExp, found: Set<string>): void {\n  rx.lastIndex = 0;\n  let m: RegExpExecArray | null;\n  while ((m = rx.exec(text)) !== null) {\n    if (m[1]) found.add(m[1]);\n  }\n}\n\nfunction collectDestructured(text: string, found: Set<string>): void {\n  ENV_DESTRUCT_RX.lastIndex = 0;\n  let m: RegExpExecArray | null;\n  while ((m = ENV_DESTRUCT_RX.exec(text)) !== null) {\n    const inner = m[1];\n    if (!inner) continue;\n    for (const part of inner.split(',')) {\n      const trimmed = part.trim();\n      if (!trimmed) continue;\n      const head = trimmed.split(/\\s*[=:]/)[0]?.trim() ?? '';\n      const name = head.replace(/^\\.\\.\\./, '').trim();\n      if (KEY_RX.test(name)) found.add(name);\n    }\n  }\n}\n\n/**\n * Extract environment variable names referenced in source text.\n * Supports dot access, bracket access, and simple `const { A, B } = process.env`.\n * Does not resolve dynamic keys (`process.env[name]`).\n */\nexport function scanSourceForEnv(text: string): Set<string> {\n  const found = new Set<string>();\n  for (const rx of [ENV_DOT_RX, META_DOT_RX, ENV_BRACKET_RX, META_BRACKET_RX]) {\n    collectMatches(text, rx, found);\n  }\n  collectDestructured(text, found);\n  return found;\n}\n","import { readdir, readFile, stat } from 'node:fs/promises';\nimport path from 'node:path';\n\nconst SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.turbo']);\n\nconst SOURCE_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte']);\n\nfunction pathIgnored(rel: string, patterns: string[]): boolean {\n  const norm = rel.replace(/\\\\/g, '/');\n  return patterns.some((pat) => {\n    if (pat.includes('*')) {\n      const re = new RegExp(\n        '^' + pat.replace(/\\*\\*/g, '.*').replace(/\\*/g, '[^/]*').replace(/\\?/g, '.') + '$',\n      );\n      return re.test(norm);\n    }\n    return norm.includes(pat.replace(/\\\\/g, '/'));\n  });\n}\n\n/**\n * Recursively list source files under `root`, honouring ignore globs (simple `*` / `**`).\n */\nexport async function listSourceFiles(root: string, ignore: string[] = []): Promise<string[]> {\n  const out: string[] = [];\n\n  async function walk(dir: string): Promise<void> {\n    const entries = await readdir(dir, { withFileTypes: true });\n    for (const ent of entries) {\n      const full = path.join(dir, ent.name);\n      const rel = path.relative(root, full);\n      if (pathIgnored(rel, ignore)) continue;\n      if (ent.isDirectory()) {\n        if (SKIP_DIRS.has(ent.name)) continue;\n        await walk(full);\n      } else if (ent.isFile()) {\n        const ext = path.extname(ent.name);\n        if (SOURCE_EXT.has(ext)) out.push(full);\n      }\n    }\n  }\n\n  const st = await stat(root);\n  if (!st.isDirectory()) return out;\n  await walk(root);\n  return out;\n}\n\nexport async function readSources(paths: string[]): Promise<Map<string, string>> {\n  const map = new Map<string, string>();\n  await Promise.all(\n    paths.map(async (p) => {\n      const text = await readFile(p, 'utf8');\n      map.set(p, text);\n    }),\n  );\n  return map;\n}\n","import { readFileSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\n\n/** Read version from package.json next to compiled CLI (works for ESM + CJS bins). */\nexport function readPackageVersion(): string {\n  try {\n    const entry = process.argv[1];\n    if (!entry) return '0.0.0';\n    const pkgPath = join(dirname(entry), '..', 'package.json');\n    const parsed: unknown = JSON.parse(readFileSync(pkgPath, 'utf8'));\n    if (parsed && typeof parsed === 'object' && 'version' in parsed) {\n      return (parsed as { version: string }).version;\n    }\n  } catch {\n    // ignore\n  }\n  return '0.0.0';\n}\n"],"mappings":"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","names":["path","readFile","path","path","readFile","path"]}

package/dist/index.cjs

@@ -0,0 +1,205 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  analyzeEnv: () => analyzeEnv,
+  formatEnvExampleAppend: () => formatEnvExampleAppend,
+  parseEnvExample: () => parseEnvExample,
+  scanSourceForEnv: () => scanSourceForEnv,
+  shouldFail: () => shouldFail,
+  suggestEnvExampleLines: () => suggestEnvExampleLines
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/analyze.ts
+var import_promises2 = require("fs/promises");
+var import_node_path2 = __toESM(require("path"), 1);
+
+// src/env-file.ts
+function parseEnvExample(content) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    const key = (eq === -1 ? trimmed : trimmed.slice(0, eq)).trim();
+    if (/^[A-Z_][A-Z0-9_]*$/.test(key)) keys.add(key);
+  }
+  return keys;
+}
+function suggestEnvExampleLines(keys) {
+  return keys.map((k) => `${k}=`);
+}
+function formatEnvExampleAppend(keys) {
+  if (keys.length === 0) return "";
+  const body = keys.map((k) => `${k}=
+`).join("");
+  return `
+# suggested by env-doctor
+${body}`;
+}
+
+// src/scan.ts
+var ENV_DOT_RX = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+var META_DOT_RX = /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/g;
+var ENV_BRACKET_RX = /process\.env\[['"]([A-Z_][A-Z0-9_]*)['"]\]/g;
+var META_BRACKET_RX = /import\.meta\.env\[['"]([A-Z_][A-Z0-9_]*)['"]\]/g;
+var ENV_DESTRUCT_RX = /\{\s*([^}]+)\s*\}\s*=\s*process\.env\b/g;
+var KEY_RX = /^[A-Z_][A-Z0-9_]*$/;
+function collectMatches(text, rx, found) {
+  rx.lastIndex = 0;
+  let m;
+  while ((m = rx.exec(text)) !== null) {
+    if (m[1]) found.add(m[1]);
+  }
+}
+function collectDestructured(text, found) {
+  ENV_DESTRUCT_RX.lastIndex = 0;
+  let m;
+  while ((m = ENV_DESTRUCT_RX.exec(text)) !== null) {
+    const inner = m[1];
+    if (!inner) continue;
+    for (const part of inner.split(",")) {
+      const trimmed = part.trim();
+      if (!trimmed) continue;
+      const head = trimmed.split(/\s*[=:]/)[0]?.trim() ?? "";
+      const name = head.replace(/^\.\.\./, "").trim();
+      if (KEY_RX.test(name)) found.add(name);
+    }
+  }
+}
+function scanSourceForEnv(text) {
+  const found = /* @__PURE__ */ new Set();
+  for (const rx of [ENV_DOT_RX, META_DOT_RX, ENV_BRACKET_RX, META_BRACKET_RX]) {
+    collectMatches(text, rx, found);
+  }
+  collectDestructured(text, found);
+  return found;
+}
+
+// src/walk.ts
+var import_promises = require("fs/promises");
+var import_node_path = __toESM(require("path"), 1);
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "coverage", ".turbo"]);
+var SOURCE_EXT = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte"]);
+function pathIgnored(rel, patterns) {
+  const norm = rel.replace(/\\/g, "/");
+  return patterns.some((pat) => {
+    if (pat.includes("*")) {
+      const re = new RegExp(
+        "^" + pat.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\?/g, ".") + "$"
+      );
+      return re.test(norm);
+    }
+    return norm.includes(pat.replace(/\\/g, "/"));
+  });
+}
+async function listSourceFiles(root, ignore = []) {
+  const out = [];
+  async function walk(dir) {
+    const entries = await (0, import_promises.readdir)(dir, { withFileTypes: true });
+    for (const ent of entries) {
+      const full = import_node_path.default.join(dir, ent.name);
+      const rel = import_node_path.default.relative(root, full);
+      if (pathIgnored(rel, ignore)) continue;
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) continue;
+        await walk(full);
+      } else if (ent.isFile()) {
+        const ext = import_node_path.default.extname(ent.name);
+        if (SOURCE_EXT.has(ext)) out.push(full);
+      }
+    }
+  }
+  const st = await (0, import_promises.stat)(root);
+  if (!st.isDirectory()) return out;
+  await walk(root);
+  return out;
+}
+async function readSources(paths) {
+  const map = /* @__PURE__ */ new Map();
+  await Promise.all(
+    paths.map(async (p) => {
+      const text = await (0, import_promises.readFile)(p, "utf8");
+      map.set(p, text);
+    })
+  );
+  return map;
+}
+
+// src/analyze.ts
+async function analyzeEnv(options = {}) {
+  const root = import_node_path2.default.resolve(options.root ?? process.cwd());
+  const envPath = import_node_path2.default.resolve(options.envExamplePath ?? import_node_path2.default.join(root, ".env.example"));
+  const ignore = options.ignore ?? [];
+  let documented = /* @__PURE__ */ new Set();
+  let envExampleFound = false;
+  try {
+    await (0, import_promises2.access)(envPath);
+    envExampleFound = true;
+    const example = await (0, import_promises2.readFile)(envPath, "utf8");
+    documented = parseEnvExample(example);
+  } catch {
+    documented = /* @__PURE__ */ new Set();
+  }
+  const files = await listSourceFiles(root, ignore);
+  const sources = await readSources(files);
+  const used = /* @__PURE__ */ new Set();
+  for (const text of sources.values()) {
+    for (const k of scanSourceForEnv(text)) used.add(k);
+  }
+  const missingInExample = [...used].filter((k) => !documented.has(k)).sort();
+  const unusedInCode = [...documented].filter((k) => !used.has(k)).sort();
+  return {
+    usedInCode: [...used].sort(),
+    documented: [...documented].sort(),
+    missingInExample,
+    unusedInCode,
+    ok: missingInExample.length === 0 && unusedInCode.length === 0,
+    envExamplePath: envPath,
+    envExampleFound
+  };
+}
+function shouldFail(report, failOn) {
+  if (failOn === "missing") return report.missingInExample.length > 0;
+  if (failOn === "unused") return report.unusedInCode.length > 0;
+  return !report.ok;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  analyzeEnv,
+  formatEnvExampleAppend,
+  parseEnvExample,
+  scanSourceForEnv,
+  shouldFail,
+  suggestEnvExampleLines
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/analyze.ts","../src/env-file.ts","../src/scan.ts","../src/walk.ts"],"sourcesContent":["export { analyzeEnv, shouldFail } from './analyze.js';\nexport type { EnvDoctorOptions, EnvDoctorReport, FailOn } from './analyze.js';\nexport { scanSourceForEnv } from './scan.js';\nexport {\n  formatEnvExampleAppend,\n  parseEnvExample,\n  suggestEnvExampleLines,\n} from './env-file.js';\n","import { access, readFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport { parseEnvExample } from './env-file.js';\nimport { scanSourceForEnv } from './scan.js';\nimport { listSourceFiles, readSources } from './walk.js';\n\nexport type FailOn = 'missing' | 'unused' | 'any';\n\nexport interface EnvDoctorOptions {\n  root?: string;\n  envExamplePath?: string;\n  ignore?: string[];\n}\n\nexport interface EnvDoctorReport {\n  usedInCode: string[];\n  documented: string[];\n  missingInExample: string[];\n  unusedInCode: string[];\n  ok: boolean;\n  /** Resolved path to the env example file that was read (or attempted). */\n  envExamplePath: string;\n  /** False when the env example file does not exist (all keys treated as undocumented). */\n  envExampleFound: boolean;\n}\n\n/**\n * Compare env usage in source against `.env.example`.\n */\nexport async function analyzeEnv(options: EnvDoctorOptions = {}): Promise<EnvDoctorReport> {\n  const root = path.resolve(options.root ?? process.cwd());\n  const envPath = path.resolve(options.envExamplePath ?? path.join(root, '.env.example'));\n  const ignore = options.ignore ?? [];\n\n  let documented = new Set<string>();\n  let envExampleFound = false;\n  try {\n    await access(envPath);\n    envExampleFound = true;\n    const example = await readFile(envPath, 'utf8');\n    documented = parseEnvExample(example);\n  } catch {\n    documented = new Set();\n  }\n\n  const files = await listSourceFiles(root, ignore);\n  const sources = await readSources(files);\n  const used = new Set<string>();\n  for (const text of sources.values()) {\n    for (const k of scanSourceForEnv(text)) used.add(k);\n  }\n\n  const missingInExample = [...used].filter((k) => !documented.has(k)).sort();\n  const unusedInCode = [...documented].filter((k) => !used.has(k)).sort();\n\n  return {\n    usedInCode: [...used].sort(),\n    documented: [...documented].sort(),\n    missingInExample,\n    unusedInCode,\n    ok: missingInExample.length === 0 && unusedInCode.length === 0,\n    envExamplePath: envPath,\n    envExampleFound,\n  };\n}\n\nexport function shouldFail(report: EnvDoctorReport, failOn: FailOn): boolean {\n  if (failOn === 'missing') return report.missingInExample.length > 0;\n  if (failOn === 'unused') return report.unusedInCode.length > 0;\n  return !report.ok;\n}\n","/**\n * Parse `.env.example` style files (KEY=value, comments and blanks ignored).\n */\nexport function parseEnvExample(content: string): Set<string> {\n  const keys = new Set<string>();\n  for (const line of content.split(/\\r?\\n/)) {\n    const trimmed = line.trim();\n    if (!trimmed || trimmed.startsWith('#')) continue;\n    const eq = trimmed.indexOf('=');\n    const key = (eq === -1 ? trimmed : trimmed.slice(0, eq)).trim();\n    if (/^[A-Z_][A-Z0-9_]*$/.test(key)) keys.add(key);\n  }\n  return keys;\n}\n\n/** Lines to append when keys are missing from `.env.example`. */\nexport function suggestEnvExampleLines(keys: string[]): string[] {\n  return keys.map((k) => `${k}=`);\n}\n\nexport function formatEnvExampleAppend(keys: string[]): string {\n  if (keys.length === 0) return '';\n  const body = keys.map((k) => `${k}=\\n`).join('');\n  return `\\n# suggested by env-doctor\\n${body}`;\n}\n","const ENV_DOT_RX = /process\\.env\\.([A-Z_][A-Z0-9_]*)/g;\nconst META_DOT_RX = /import\\.meta\\.env\\.([A-Z_][A-Z0-9_]*)/g;\nconst ENV_BRACKET_RX = /process\\.env\\[['\"]([A-Z_][A-Z0-9_]*)['\"]\\]/g;\nconst META_BRACKET_RX = /import\\.meta\\.env\\[['\"]([A-Z_][A-Z0-9_]*)['\"]\\]/g;\nconst ENV_DESTRUCT_RX = /\\{\\s*([^}]+)\\s*\\}\\s*=\\s*process\\.env\\b/g;\n\nconst KEY_RX = /^[A-Z_][A-Z0-9_]*$/;\n\nfunction collectMatches(text: string, rx: RegExp, found: Set<string>): void {\n  rx.lastIndex = 0;\n  let m: RegExpExecArray | null;\n  while ((m = rx.exec(text)) !== null) {\n    if (m[1]) found.add(m[1]);\n  }\n}\n\nfunction collectDestructured(text: string, found: Set<string>): void {\n  ENV_DESTRUCT_RX.lastIndex = 0;\n  let m: RegExpExecArray | null;\n  while ((m = ENV_DESTRUCT_RX.exec(text)) !== null) {\n    const inner = m[1];\n    if (!inner) continue;\n    for (const part of inner.split(',')) {\n      const trimmed = part.trim();\n      if (!trimmed) continue;\n      const head = trimmed.split(/\\s*[=:]/)[0]?.trim() ?? '';\n      const name = head.replace(/^\\.\\.\\./, '').trim();\n      if (KEY_RX.test(name)) found.add(name);\n    }\n  }\n}\n\n/**\n * Extract environment variable names referenced in source text.\n * Supports dot access, bracket access, and simple `const { A, B } = process.env`.\n * Does not resolve dynamic keys (`process.env[name]`).\n */\nexport function scanSourceForEnv(text: string): Set<string> {\n  const found = new Set<string>();\n  for (const rx of [ENV_DOT_RX, META_DOT_RX, ENV_BRACKET_RX, META_BRACKET_RX]) {\n    collectMatches(text, rx, found);\n  }\n  collectDestructured(text, found);\n  return found;\n}\n","import { readdir, readFile, stat } from 'node:fs/promises';\nimport path from 'node:path';\n\nconst SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.turbo']);\n\nconst SOURCE_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte']);\n\nfunction pathIgnored(rel: string, patterns: string[]): boolean {\n  const norm = rel.replace(/\\\\/g, '/');\n  return patterns.some((pat) => {\n    if (pat.includes('*')) {\n      const re = new RegExp(\n        '^' + pat.replace(/\\*\\*/g, '.*').replace(/\\*/g, '[^/]*').replace(/\\?/g, '.') + '$',\n      );\n      return re.test(norm);\n    }\n    return norm.includes(pat.replace(/\\\\/g, '/'));\n  });\n}\n\n/**\n * Recursively list source files under `root`, honouring ignore globs (simple `*` / `**`).\n */\nexport async function listSourceFiles(root: string, ignore: string[] = []): Promise<string[]> {\n  const out: string[] = [];\n\n  async function walk(dir: string): Promise<void> {\n    const entries = await readdir(dir, { withFileTypes: true });\n    for (const ent of entries) {\n      const full = path.join(dir, ent.name);\n      const rel = path.relative(root, full);\n      if (pathIgnored(rel, ignore)) continue;\n      if (ent.isDirectory()) {\n        if (SKIP_DIRS.has(ent.name)) continue;\n        await walk(full);\n      } else if (ent.isFile()) {\n        const ext = path.extname(ent.name);\n        if (SOURCE_EXT.has(ext)) out.push(full);\n      }\n    }\n  }\n\n  const st = await stat(root);\n  if (!st.isDirectory()) return out;\n  await walk(root);\n  return out;\n}\n\nexport async function readSources(paths: string[]): Promise<Map<string, string>> {\n  const map = new Map<string, string>();\n  await Promise.all(\n    paths.map(async (p) => {\n      const text = await readFile(p, 'utf8');\n      map.set(p, text);\n    }),\n  );\n  return map;\n}\n"],"mappings":"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","names":["import_promises","import_node_path","path","path"]}

package/dist/index.d.cts

@@ -0,0 +1,39 @@
+type FailOn = 'missing' | 'unused' | 'any';
+interface EnvDoctorOptions {
+    root?: string;
+    envExamplePath?: string;
+    ignore?: string[];
+}
+interface EnvDoctorReport {
+    usedInCode: string[];
+    documented: string[];
+    missingInExample: string[];
+    unusedInCode: string[];
+    ok: boolean;
+    /** Resolved path to the env example file that was read (or attempted). */
+    envExamplePath: string;
+    /** False when the env example file does not exist (all keys treated as undocumented). */
+    envExampleFound: boolean;
+}
+/**
+ * Compare env usage in source against `.env.example`.
+ */
+declare function analyzeEnv(options?: EnvDoctorOptions): Promise<EnvDoctorReport>;
+declare function shouldFail(report: EnvDoctorReport, failOn: FailOn): boolean;
+
+/**
+ * Extract environment variable names referenced in source text.
+ * Supports dot access, bracket access, and simple `const { A, B } = process.env`.
+ * Does not resolve dynamic keys (`process.env[name]`).
+ */
+declare function scanSourceForEnv(text: string): Set<string>;
+
+/**
+ * Parse `.env.example` style files (KEY=value, comments and blanks ignored).
+ */
+declare function parseEnvExample(content: string): Set<string>;
+/** Lines to append when keys are missing from `.env.example`. */
+declare function suggestEnvExampleLines(keys: string[]): string[];
+declare function formatEnvExampleAppend(keys: string[]): string;
+
+export { type EnvDoctorOptions, type EnvDoctorReport, type FailOn, analyzeEnv, formatEnvExampleAppend, parseEnvExample, scanSourceForEnv, shouldFail, suggestEnvExampleLines };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+type FailOn = 'missing' | 'unused' | 'any';
+interface EnvDoctorOptions {
+    root?: string;
+    envExamplePath?: string;
+    ignore?: string[];
+}
+interface EnvDoctorReport {
+    usedInCode: string[];
+    documented: string[];
+    missingInExample: string[];
+    unusedInCode: string[];
+    ok: boolean;
+    /** Resolved path to the env example file that was read (or attempted). */
+    envExamplePath: string;
+    /** False when the env example file does not exist (all keys treated as undocumented). */
+    envExampleFound: boolean;
+}
+/**
+ * Compare env usage in source against `.env.example`.
+ */
+declare function analyzeEnv(options?: EnvDoctorOptions): Promise<EnvDoctorReport>;
+declare function shouldFail(report: EnvDoctorReport, failOn: FailOn): boolean;
+
+/**
+ * Extract environment variable names referenced in source text.
+ * Supports dot access, bracket access, and simple `const { A, B } = process.env`.
+ * Does not resolve dynamic keys (`process.env[name]`).
+ */
+declare function scanSourceForEnv(text: string): Set<string>;
+
+/**
+ * Parse `.env.example` style files (KEY=value, comments and blanks ignored).
+ */
+declare function parseEnvExample(content: string): Set<string>;
+/** Lines to append when keys are missing from `.env.example`. */
+declare function suggestEnvExampleLines(keys: string[]): string[];
+declare function formatEnvExampleAppend(keys: string[]): string;
+
+export { type EnvDoctorOptions, type EnvDoctorReport, type FailOn, analyzeEnv, formatEnvExampleAppend, parseEnvExample, scanSourceForEnv, shouldFail, suggestEnvExampleLines };