env-drift-check 0.1.3 → 0.1.5

package/README.md

@@ -11,23 +11,29 @@
 
 ##  Why use this?
 
-| Feature | Other Tools (dotenv-safe, etc.) | **env-drift-check** |
+| Feature | Other Tools | **env-drift-check** |
 | :--- | :--- | :--- |
 | **Missing Keys** | Crash & Exit  |  **Interactive Setup Wizard**  |
 | **Validation** | Basic Existence Check | **Rich Types** (Email, URL, Regex, Number)  |
 | **Onboarding** | Manual (Read docs → Copy → Paste) | **Automated** (Run command → Fill prompts)  |
 | **Drift Detection** | Static | **Real-time** comparison with `.env.example` |
 
-##  Features
+###  Features
 
 - **Interactive Mode**: Automatically detects missing keys and prompts you to fill them in via CLI.
 - **Smart Schema Validation**: Enforce types like `email`, `url`, `number`, `boolean`, `enum`, and custom `regex`.
 - **Drift Detection**: Instantly compare your local environment against the team's `.env.example`.
-- **CI/CD Ready**: Use strict mode to fail builds if environment variables are missing or invalid.
 - **Zero Config**: Works out of the box, or add `envwise.config.json` for advanced validation rules.
 
+## 📖 Documentation
+
+- [CLI Usage](./docs/CLI-Usage.md) - Command line flags and examples.
+- [Configuration](./docs/Configuration.md) - Advanced validation rules and `envwise.config.json`.
+- [Programmatic API](./docs/API-Reference.md) - Using the package in your code.
+
 ## Installation
 
+
 Install globally or as a dev dependency:
 
 ```bash
@@ -36,7 +42,7 @@ npm install -g env-drift-check
 npm install --save-dev env-drift-check
 ```
 
-## 🛠 Usage
+## Usage
 
 ### 1. Basic Check
 Check if your `.env` is missing any keys defined in `.env.example`. This is great for a quick status check.

package/dist/config/loadConfig.d.ts

@@ -1,2 +1,8 @@
 import { Config } from "../types";
+/**
+ * Loads the project configuration from 'envwise.config.json' if it exists.
+ * Falls back to default configuration if no file is found.
+ *
+ * @returns The consolidated configuration object
+ */
 export declare function loadConfig(): Config;

package/dist/config/loadConfig.js

@@ -10,6 +10,12 @@ const DEFAULT_CONFIG = {
     baseEnv: ".env.example",
     rules: {}
 };
+/**
+ * Loads the project configuration from 'envwise.config.json' if it exists.
+ * Falls back to default configuration if no file is found.
+ *
+ * @returns The consolidated configuration object
+ */
 function loadConfig() {
     const configPath = path_1.default.resolve("envwise.config.json");
     if (!fs_1.default.existsSync(configPath)) {

package/dist/engine/driftChecker.d.ts

@@ -1,2 +1,11 @@
 import { DriftResult, Config } from "../types";
+/**
+ * Compares a base environment (template) against a target environment (actual)
+ * and returns the differences including missing keys, extra keys, and value mismatches.
+ *
+ * @param base - The record representing the template environment (e.g., .env.example)
+ * @param target - The record representing the actual environment (e.g., .env)
+ * @param config - Configuration object containing validation rules
+ * @returns An object containing the results of the drift check
+ */
 export declare function checkDrift(base: Record<string, string>, target: Record<string, string>, config: Config): DriftResult;

package/dist/engine/driftChecker.js

@@ -2,6 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkDrift = checkDrift;
 const validator_1 = require("./validator");
+/**
+ * Compares a base environment (template) against a target environment (actual)
+ * and returns the differences including missing keys, extra keys, and value mismatches.
+ *
+ * @param base - The record representing the template environment (e.g., .env.example)
+ * @param target - The record representing the actual environment (e.g., .env)
+ * @param config - Configuration object containing validation rules
+ * @returns An object containing the results of the drift check
+ */
 function checkDrift(base, target, config) {
     const result = {
         missing: [],

package/dist/engine/envParser.d.ts

@@ -1 +1,9 @@
+/**
+ * Parses a .env file from the given file system path.
+ * It handles comments, empty lines, and quoted values.
+ *
+ * @param path - The absolute or relative path to the .env file
+ * @returns A record containing key-value pairs of the environment variables
+ * @throws {Error} If the file does not exist
+ */
 export declare function parseEnv(path: string): Record<string, string>;

package/dist/engine/envParser.js

@@ -5,6 +5,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseEnv = parseEnv;
 const fs_1 = __importDefault(require("fs"));
+/**
+ * Parses a .env file from the given file system path.
+ * It handles comments, empty lines, and quoted values.
+ *
+ * @param path - The absolute or relative path to the .env file
+ * @returns A record containing key-value pairs of the environment variables
+ * @throws {Error} If the file does not exist
+ */
 function parseEnv(path) {
     if (!fs_1.default.existsSync(path)) {
         throw new Error(`Env file not found: ${path}`);

package/dist/engine/interactive.d.ts

@@ -1,2 +1,11 @@
 import { Config } from "../types";
+/**
+ * Launches an interactive CLI wizard to help users fill in missing environment variables.
+ * Uses the 'prompts' package to collect user input with validation.
+ *
+ * @param missingKeys - An array of environment variable keys that are missing
+ * @param baseEnv - The template environment mapping
+ * @param config - The tool configuration containing validation rules
+ * @returns A promise that resolves to a record of the newly filled key-value pairs
+ */
 export declare function interactiveSetup(missingKeys: string[], baseEnv: Record<string, string>, config: Config): Promise<Record<string, string>>;

package/dist/engine/interactive.js

@@ -6,6 +6,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.interactiveSetup = interactiveSetup;
 const prompts_1 = __importDefault(require("prompts"));
 const validator_1 = require("./validator");
+/**
+ * Launches an interactive CLI wizard to help users fill in missing environment variables.
+ * Uses the 'prompts' package to collect user input with validation.
+ *
+ * @param missingKeys - An array of environment variable keys that are missing
+ * @param baseEnv - The template environment mapping
+ * @param config - The tool configuration containing validation rules
+ * @returns A promise that resolves to a record of the newly filled key-value pairs
+ */
 async function interactiveSetup(missingKeys, baseEnv, config) {
     const newValues = {};
     console.log("\n🛠  Interactive Setup: Let's fill in the missing variables.\n");

package/dist/engine/validator.d.ts

@@ -1,2 +1,12 @@
 import { Rule } from "../types";
+/**
+ * Validates a single environment variable value against a set of rules.
+ * Supports string length, number ranges, boolean flags, enums, emails, URLs, and custom regex.
+ *
+ * @param key - The name of the environment variable
+ * @param value - The value to validate
+ * @param rule - The validation rule configuration for this key
+ * @param env - The current environment (e.g., NODE_ENV) for conditional rules
+ * @returns A string containing the error message if validation fails, otherwise null
+ */
 export declare function validateValue(key: string, value: string, rule: Rule, env: string): string | null;

package/dist/engine/validator.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateValue = validateValue;
+/**
+ * Validates a single environment variable value against a set of rules.
+ * Supports string length, number ranges, boolean flags, enums, emails, URLs, and custom regex.
+ *
+ * @param key - The name of the environment variable
+ * @param value - The value to validate
+ * @param rule - The validation rule configuration for this key
+ * @param env - The current environment (e.g., NODE_ENV) for conditional rules
+ * @returns A string containing the error message if validation fails, otherwise null
+ */
 function validateValue(key, value, rule, env) {
     if (!value && rule.required !== false) {
         return `${key} is required`;

package/dist/types.d.ts

@@ -1,29 +1,56 @@
+/**
+ * Represents a validation rule for an environment variable.
+ */
 export interface Rule {
+    /** The data type of the variable. Used for validation and CLI input prompts. */
     type: "string" | "number" | "boolean" | "enum" | "email" | "url" | "regex";
+    /** Allowed values if the type is 'enum'. */
     values?: string[];
+    /** Custom regular expression string if the type is 'regex'. */
     regex?: string;
+    /** Minimum length (for strings) or minimum value (for numbers). */
     min?: number;
+    /** Maximum length (for strings) or maximum value (for numbers). */
     max?: number;
+    /** A helpful description displayed during interactive CLI setup. */
     description?: string;
+    /** Environment(s) where this boolean must be false (useful for safety flags). */
     mustBeFalseIn?: string;
+    /** Whether the variable is mandatory. Defaults to true. */
     required?: boolean;
 }
+/**
+ * Global configuration for the env-drift-check tool.
+ */
 export interface Config {
+    /** The template environment file to compare against (e.g., .env.example). */
     baseEnv?: string;
+    /** A map of environment variable keys to their validation rules. */
     rules?: Record<string, Rule>;
 }
+/**
+ * Details of a mismatch between the base and target environment values.
+ */
 export interface ValueMismatch {
     key: string;
     expected: string;
     actual: string;
 }
+/**
+ * The consolidated result of an environment drift check.
+ */
 export interface DriftResult {
+    /** Keys present in the template but missing in the target. */
     missing: string[];
+    /** Keys present in the target but absent from the template. */
     extra: string[];
+    /** Validation errors based on the defined rules. */
     errors: {
         key: string;
         message: string;
     }[];
+    /** Non-critical warnings. */
     warnings: string[];
+    /** Values that differ between the template and target for the same key. */
     mismatches: ValueMismatch[];
 }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "env-drift-check",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Interactive environment variable checker and setup wizard. Sync .env files with validation (Email, URL, Regex) and prompts.",
   "keywords": [
     "env",
     "dotenv",
     "check-env",
     "dotenv-safe",
+    "env-drift-check",
     "environment-variables",
+    "env-validation",
     "config",
     "validation",
     "interactive",