@gudroniy/env-doctor 1.0.0

package/README.md

@@ -0,0 +1,75 @@
+# env-doctor
+
+CLI, который проверяет `.env` файлы на пропущенные переменные, несовпадение типов и расхождения между окружениями (dev / staging / production) — **до** того, как это сломает деплой.
+
+## Проблема
+
+Классическая ситуация: в `.env` локально всё работает, а на проде забыли добавить одну переменную — и приложение падает после деплоя. Или переменная есть, но записана не в том формате (например, `PORT=abc` вместо числа). Обычно это ловят вручную, глазами, сравнивая файлы.
+
+`env-doctor` автоматизирует эту проверку.
+
+## Установка
+
+```bash
+npm install -g env-doctor
+```
+
+Или без глобальной установки:
+
+```bash
+npx env-doctor check
+```
+
+## Быстрый старт
+
+1. Сгенерируй схему на основе рабочего `.env`:
+
+```bash
+env-doctor init --file .env
+```
+
+Это создаст `env.schema.json` — файл с описанием ожидаемых переменных и их типов (определяются автоматически).
+
+2. Отредактируй схему при необходимости — пометь необязательные переменные (`"required": false`), поправь типы.
+
+3. Проверь любой другой `.env` файл на соответствие схеме:
+
+```bash
+env-doctor check .env.production
+```
+
+Без аргументов проверяются все файлы вида `.env*` в текущей папке:
+
+```bash
+env-doctor check
+```
+
+## Пример вывода
+
+```
+.env.production
+  ✘ Переменная "API_KEY" обязательна, но пустая
+  ✘ Переменная "PORT" должна быть типа number, получено "not-a-number"
+  ✘ Отсутствует обязательная переменная "STRIPE_WEBHOOK_SECRET"
+  ⚠ Переменная "LEGACY_FLAG" не описана в схеме
+
+Итого: 3 ошибок, 1 предупреждений
+```
+
+## Использование в CI
+
+Команда завершается с кодом `1`, если найдены ошибки — удобно добавить проверку в pipeline перед деплоем:
+
+```yaml
+- run: npx env-doctor check .env.production --strict
+```
+
+Флаг `--strict` также считает ошибкой любые переменные, не описанные в схеме (например, забытые старые ключи).
+
+## Поддерживаемые типы
+
+`string`, `number`, `boolean`, `url`, `email`
+
+## Лицензия
+
+MIT

package/bin/env-doctor.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+const { program } = require('commander');
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { parseEnvFile } = require('../src/parser');
+const { inferType } = require('../src/inferType');
+const { checkEnv } = require('../src/validators');
+
+const DEFAULT_SCHEMA_FILE = 'env.schema.json';
+
+program
+  .name('env-doctor')
+  .description(
+    'Проверяет .env файлы на пропущенные переменные, несоответствие типов и расхождения между окружениями'
+  )
+  .version('1.0.0');
+
+program
+  .command('init')
+  .description('Сгенерировать env.schema.json на основе существующего .env файла')
+  .option('-f, --file <path>', 'Путь к исходному .env файлу', '.env')
+  .option('-o, --output <path>', 'Путь для сохранения схемы', DEFAULT_SCHEMA_FILE)
+  .action((opts) => {
+    const filePath = path.resolve(process.cwd(), opts.file);
+    if (!fs.existsSync(filePath)) {
+      console.error(chalk.red(`Файл не найден: ${filePath}`));
+      process.exit(1);
+    }
+
+    const { values } = parseEnvFile(filePath);
+    const schema = {};
+    for (const [key, value] of Object.entries(values)) {
+      schema[key] = { required: true, type: inferType(value) };
+    }
+
+    const schemaPath = path.resolve(process.cwd(), opts.output);
+    fs.writeFileSync(schemaPath, JSON.stringify(schema, null, 2) + '\n');
+
+    console.log(chalk.green(`✔ Схема создана: ${opts.output} (${Object.keys(schema).length} переменных)`));
+    console.log(chalk.gray('  Отредактируй файл вручную: пометь опциональные переменные, поправь типы при необходимости.'));
+  });
+
+program
+  .command('check [files...]')
+  .description('Проверить .env файлы на соответствие схеме')
+  .option('-s, --strict', 'Считать лишние переменные ошибкой, а не предупреждением')
+  .option('--schema <path>', 'Путь к файлу схемы', DEFAULT_SCHEMA_FILE)
+  .action((files, opts) => {
+    const schemaPath = path.resolve(process.cwd(), opts.schema);
+    if (!fs.existsSync(schemaPath)) {
+      console.error(chalk.red(`Схема не найдена: ${schemaPath}`));
+      console.error(chalk.gray('  Запусти "env-doctor init" сначала, чтобы её создать.'));
+      process.exit(1);
+    }
+    const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+
+    let targetFiles = files && files.length ? files : null;
+    if (!targetFiles) {
+      targetFiles = fs
+        .readdirSync(process.cwd())
+        .filter((f) => /^\.env(\..+)?$/.test(f));
+    }
+
+    if (targetFiles.length === 0) {
+      console.error(chalk.red('Не найдено ни одного .env файла для проверки.'));
+      process.exit(1);
+    }
+
+    let totalErrors = 0;
+    let totalWarnings = 0;
+
+    for (const file of targetFiles) {
+      const filePath = path.resolve(process.cwd(), file);
+      console.log(chalk.bold(`\n${file}`));
+
+      if (!fs.existsSync(filePath)) {
+        console.log(chalk.red('  ✘ файл не найден'));
+        totalErrors++;
+        continue;
+      }
+
+      const { values, duplicates } = parseEnvFile(filePath);
+      const issues = checkEnv(schema, values, { strict: Boolean(opts.strict) });
+
+      duplicates.forEach((d) => {
+        issues.push({
+          level: 'warning',
+          key: d.key,
+          message: `Дублирующийся ключ "${d.key}" (строка ${d.line})`,
+        });
+      });
+
+      if (issues.length === 0) {
+        console.log(chalk.green('  ✔ Всё в порядке'));
+        continue;
+      }
+
+      issues.forEach((issue) => {
+        const icon = issue.level === 'error' ? chalk.red('✘') : chalk.yellow('⚠');
+        console.log(`  ${icon} ${issue.message}`);
+        if (issue.level === 'error') totalErrors++;
+        else totalWarnings++;
+      });
+    }
+
+    console.log('');
+    console.log(chalk.bold(`Итого: ${totalErrors} ошибок, ${totalWarnings} предупреждений`));
+
+    if (totalErrors > 0) process.exit(1);
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@gudroniy/env-doctor",
+  "version": "1.0.0",
+  "description": "CLI, который проверяет .env файлы на пропущенные переменные, несовпадение типов и расхождения между окружениями",
+  "bin": {
+    "env-doctor": "./bin/env-doctor.js"
+  },
+  "main": "src/index.js",
+  "license": "MIT",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": ["env", "dotenv", "cli", "devtools", "validation"],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

package/src/inferType.js

@@ -0,0 +1,14 @@
+/**
+ * Пытается угадать тип значения переменной окружения.
+ * Используется командой `init` для генерации схемы.
+ */
+function inferType(value) {
+  if (value === '') return 'string';
+  if (/^(true|false)$/i.test(value)) return 'boolean';
+  if (/^-?\d+(\.\d+)?$/.test(value)) return 'number';
+  if (/^https?:\/\/.+/i.test(value)) return 'url';
+  if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return 'email';
+  return 'string';
+}
+
+module.exports = { inferType };

package/src/parser.js

@@ -0,0 +1,42 @@
+const fs = require('fs');
+
+/**
+ * Парсит .env файл в объект ключ-значение.
+ * Возвращает также список дублирующихся ключей.
+ */
+function parseEnvFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split(/\r?\n/);
+  const values = {};
+  const duplicates = [];
+  const seen = new Set();
+
+  lines.forEach((rawLine, idx) => {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) return;
+
+    const eqIndex = line.indexOf('=');
+    if (eqIndex === -1) return;
+
+    const key = line.slice(0, eqIndex).trim();
+    let value = line.slice(eqIndex + 1).trim();
+
+    // убираем окружающие кавычки
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    if (seen.has(key)) {
+      duplicates.push({ key, line: idx + 1 });
+    }
+    seen.add(key);
+    values[key] = value;
+  });
+
+  return { values, duplicates };
+}
+
+module.exports = { parseEnvFile };

package/src/validators.js

@@ -0,0 +1,64 @@
+function validateType(value, expectedType) {
+  if (!expectedType || expectedType === 'string') return true;
+  if (expectedType === 'number') return /^-?\d+(\.\d+)?$/.test(value);
+  if (expectedType === 'boolean') return /^(true|false)$/i.test(value);
+  if (expectedType === 'url') return /^https?:\/\/.+/i.test(value);
+  if (expectedType === 'email') return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+  return true;
+}
+
+/**
+ * Сравнивает значения из .env файла со схемой.
+ * Возвращает список проблем: { level: 'error' | 'warning', key, message }
+ */
+function checkEnv(schema, envValues, { strict = false } = {}) {
+  const issues = [];
+
+  for (const [key, rule] of Object.entries(schema)) {
+    const hasKey = Object.prototype.hasOwnProperty.call(envValues, key);
+
+    if (rule.required && !hasKey) {
+      issues.push({
+        level: 'error',
+        key,
+        message: `Отсутствует обязательная переменная "${key}"`,
+      });
+      continue;
+    }
+
+    if (hasKey) {
+      const value = envValues[key];
+
+      if (rule.required && value === '') {
+        issues.push({
+          level: 'error',
+          key,
+          message: `Переменная "${key}" обязательна, но пустая`,
+        });
+        continue;
+      }
+
+      if (value !== '' && rule.type && !validateType(value, rule.type)) {
+        issues.push({
+          level: 'error',
+          key,
+          message: `Переменная "${key}" должна быть типа ${rule.type}, получено "${value}"`,
+        });
+      }
+    }
+  }
+
+  for (const key of Object.keys(envValues)) {
+    if (!schema[key]) {
+      issues.push({
+        level: strict ? 'error' : 'warning',
+        key,
+        message: `Переменная "${key}" не описана в схеме`,
+      });
+    }
+  }
+
+  return issues;
+}
+
+module.exports = { checkEnv, validateType };