envprobe 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Bitreon]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+# envcheck-cli
+
+## The Origin Story (Or: How Coffee Led to Code)
+
+So there I was, sitting on my sofa, sipping my coffee on a perfectly ordinary Saturday morning. You know that moment when the caffeine hits just right and your brain suddenly decides to replay every production incident from the past year? Yeah, that happened.
+
+I was thinking about *that one time* when the staging environment exploded because someone added `DATABASE_URL` to the code but forgot to document it in `.env.example`. The new dev spent three hours debugging why their local setup wouldn't work. Three. Hours. For a missing environment variable.
+
+My coffee was getting cold as I stared at the ceiling, and I thought: "Why isn't there a tool that just... checks this stuff?" You know, something that scans your code, looks at what env vars you're actually using, and yells at you if they're not documented. Something simple. Something that doesn't require installing half of npm to work.
+
+So I did what any reasonable developer does when caffeinated and slightly annoyed: I built it.
+
+And thus, envcheck-cli was born. From a sofa. With lukewarm coffee. Living its best life as a zero-dependency CLI tool that saves developers from the ancient curse of undocumented environment variables.
+
+## What This Thing Actually Does
+
+envcheck scans your codebase and compares environment variable usage against your `.env.example` file. It's like a spell-checker, but for env vars. It catches three types of problems:
+
+- **MISSING** - You're using `process.env.SECRET_API_KEY` in your code, but `.env.example` has never heard of it. Rookie mistake.
+- **UNUSED** - You documented `LEGACY_FEATURE_FLAG` in `.env.example`, but it's not referenced anywhere. Time to clean house.
+- **UNDOCUMENTED** - The variable exists and is used, but there's no comment explaining what it does. Future you will hate present you for this.
+
+## Why You Might Actually Want This
+
+- **Zero dependencies** - Seriously. None. Just Node.js built-ins. Your `node_modules` folder thanks me.
+- **Multi-language support** - JavaScript, TypeScript, Python, Go, Ruby, Rust, Shell scripts. I got you.
+- **Multiple output formats** - Human-readable text, JSON for your scripts, GitHub Actions annotations for your CI/CD pipeline.
+- **Actually fast** - No AI, no blockchain, no unnecessary complexity. Just good old-fashioned file scanning.
+- **CI/CD ready** - Configurable failure conditions so you can enforce env var hygiene in your pipeline.
+- **Interactive REPL** - Explore and fix issues in an interactive shell with tab completion and command history.
+- **Watch mode** - Automatically rerun validation when files change during development.
+- **Auto-fix** - Automatically add missing variables to .env.example with smart defaults.
+- **Intelligent suggestions** - Get actionable hints including typo detection and smart example values.
+- **Configuration files** - Save your settings in `.envcheckrc.json` for consistent team workflows.
+
+## Supported Languages
+
+Because not everyone writes JavaScript (shocking, I know):
+
+- JavaScript/TypeScript (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`)
+- Python (`.py`)
+- Go (`.go`)
+- Ruby (`.rb`)
+- Rust (`.rs`)
+- Shell/Bash (`.sh`, `.bash`, `.zsh`)
+
+## Requirements
+
+- Node.js 18.0.0 or higher (because we're living in the future)
+
+## Installation
+
+```bash
+npm install -g envcheck-cli
+```
+
+Or run it directly without installing:
+
+```bash
+npx envcheck-cli
+```
+
+## Quick Start
+
+The simplest way to use envcheck:
+
+```bash
+envcheck
+```
+
+That's it. It scans your current directory, checks your `.env.example`, and tells you what's wrong. But there's more if you need it.
+
+## The Evolution: From Simple to Powerful
+
+### Act I: The Basic Scan
+
+You run `envcheck` and it does its thing. Finds missing vars, unused vars, undocumented vars. Clean output. Done.
+
+```bash
+envcheck
+```
+
+But then you think: "What if I could just... stay in here? Like a conversation?"
+
+### Act II: The Interactive Mode
+
+So we built a REPL. Because sometimes you want to poke around, try different settings, see what happens.
+
+```bash
+envcheck --repl
+```
+
+Now you're in an interactive shell. Type `:help` and discover you can:
+- Change settings on the fly (`:set format json`)
+- View your command history (`:history`)
+- Get smart suggestions (`:suggest`)
+- Save your config for later (`:save`)
+
+It's like having a conversation with your environment variables. Weird, but useful.
+
+### Act III: The "I'm Coding Right Now" Mode
+
+You're deep in the zone. Writing code. Adding env vars. You don't want to keep running commands manually.
+
+```bash
+envcheck --watch
+```
+
+Now it watches your files. Every time you save, it checks again. Instant feedback. No context switching. Just code and know.
+
+### Act IV: The "Just Fix It Already" Button
+
+You've got 15 missing variables. You know they need to be in `.env.example`. You don't want to type them all out.
+
+```bash
+envcheck --fix
+```
+
+Done. It adds them for you. With smart defaults:
+- Sees `API_KEY`? Suggests `your_api_key_here`
+- Sees `DATABASE_URL`? Suggests `postgres://localhost:5432/dbname`
+- Sees `PORT`? Suggests `3000`
+
+It's not magic. It's just pattern matching. But it feels like magic at 11 PM.
+
+### Act V: The "Did You Mean...?" Feature
+
+You typed `DATABSE_URL` instead of `DATABASE_URL`. We've all been there.
+
+```bash
+envcheck
+```
+
+Output:
+```
+💡 Did you mean 'DATABASE_URL' instead of 'DATABSE_URL'? (91% similar)
+```
+
+It's like autocorrect, but for environment variables. And it doesn't change "duck" to something embarrassing.
+
+### Act VI: The Team Player
+
+Your team needs consistency. Everyone should use the same settings. So you create a config file:
+
+```json
+{
+  "path": ".",
+  "envFile": ".env.example",
+  "failOn": "missing",
+  "ignore": ["node_modules/**", "**/*.test.js"]
+}
+```
+
+Save it as `.envcheckrc.json`. Commit it. Now everyone's on the same page. No more "but it works on my machine" because of env var issues.
+
+## Real-World Scenarios (Or: How People Actually Use This)
+
+### Scenario 1: The New Developer
+
+Sarah joins your team. She clones the repo, runs `npm install`, starts the app. It crashes. "What env vars do I need?"
+
+With envcheck:
+```bash
+envcheck
+```
+
+She sees exactly what's missing. Copies them to her `.env`. App starts. She's productive in 5 minutes instead of 50.
+
+### Scenario 2: The Refactoring Session
+
+You're removing an old feature. Delete a bunch of code. But did you remove the env vars from `.env.example`?
+
+```bash
+envcheck
+```
+
+"Found 3 unused variables." Clean them up. Keep your config lean.
+
+### Scenario 3: The CI/CD Pipeline
+
+Your staging environment broke because someone forgot to document a new env var. Again.
+
+Add to your GitHub Actions:
+```yaml
+- run: envcheck --format github --fail-on missing
+```
+
+Now the PR won't merge until all env vars are documented. Problem solved.
+
+### Scenario 4: The Late Night Coding Session
+
+It's 2 AM. You're in the zone. Adding features. Adding env vars. You don't want to break your flow.
+
+```bash
+envcheck --watch
+```
+
+Terminal in the corner. Updates automatically. You see issues as they happen. Fix them before you forget.
+
+### Scenario 5: The "I'll Do It Later" Moment
+
+You added 10 new env vars. You know you need to document them. But typing them all out? Ugh.
+
+```bash
+envcheck --fix
+```
+
+It adds them all with smart defaults. You just need to update the descriptions. 2 minutes instead of 20.
+
+## All The Flags (For When You Need Control)
+
+```bash
+envcheck [path] [options]
+```
+
+**The Essentials:**
+- `--env-file <path>` - Check against a different env file (like `.env.production.example`)
+- `--format json` - Output as JSON (for scripts and tools)
+- `--format github` - GitHub Actions annotations (for CI/CD)
+- `--fail-on missing` - Exit with code 1 if issues found (for CI/CD)
+
+**The Power User Stuff:**
+- `--watch` - Auto-rerun on file changes (for development)
+- `--fix` - Auto-add missing vars to .env.example (for lazy days)
+- `--repl` - Interactive mode (for exploration)
+- `--config <path>` - Load settings from file (for teams)
+- `--ignore "**/*.test.js"` - Skip certain files (repeatable)
+
+**The "Make It Quiet" Options:**
+- `--quiet` - Only show output if there are issues
+- `--no-color` - Plain text (for logs and scripts)
+- `--no-suggestions` - Skip the helpful hints
+- `--no-progress` - No spinners or progress bars
+
+**The Obvious Ones:**
+- `--help` - Show help message
+- `--version` - Show version number
+
+## Making It Part of Your Workflow
+
+### The Pre-commit Hook (Catch Issues Before They're Committed)
+
+Create `.git/hooks/pre-commit`:
+```bash
+#!/bin/sh
+envcheck . --fail-on missing --quiet
+```
+
+Now you can't commit code that uses undocumented env vars. Your future self says thanks.
+
+### The GitHub Action (Catch Issues Before They're Merged)
+
+Add to `.github/workflows/ci.yml`:
+```yaml
+- name: Check environment variables
+  run: envcheck . --format github --fail-on all
+```
+
+PRs with missing env vars won't pass CI. No more "works on my machine" surprises in production.
+
+### The npm Script (For Your Team)
+
+Add to `package.json`:
+```json
+{
+  "scripts": {
+    "env:check": "envcheck .",
+    "env:watch": "envcheck . --watch",
+    "env:fix": "envcheck . --fix",
+    "pretest": "envcheck . --fail-on missing"
+  }
+}
+```
+
+Now everyone knows how to check env vars. `npm run env:check`. Simple.
+
+### The Docker Build (Fail Fast in Containers)
+
+Add to your `Dockerfile`:
+```dockerfile
+RUN npm install -g envcheck
+RUN envcheck . --fail-on all
+```
+
+If env vars are misconfigured, the build fails. Better to know during build than during deploy.
+
+## Want More?
+
+The docs have the deep stuff:
+- [CLI Reference](docs/CLI_REFERENCE.md) - Complete command-line flag documentation
+- [Configuration Guide](docs/CONFIGURATION.md) - All the settings, explained
+- [Examples](docs/EXAMPLES.md) - Real-world use cases and patterns
+- [Integrations](docs/INTEGRATIONS.md) - CI/CD platform setup guides
+- [REPL Guide](docs/REPL.md) - Interactive mode deep dive
+- [Advanced Features](docs/ADVANCED.md) - Plugins, caching, performance tuning
+- [Architecture](docs/ARCHITECTURE.md) - How it works under the hood
+
+## The Bottom Line
+
+envcheck started as a simple tool to solve a simple problem: keeping `.env.example` in sync with your code.
+
+Then we added a REPL because sometimes you want to explore.
+Then watch mode because developers hate context switching.
+Then auto-fix because typing is tedious.
+Then smart suggestions because typos happen.
+Then config files because teams need consistency.
+
+It's still zero dependencies. It's still fast. It's still simple at its core.
+
+But now it's also powerful when you need it to be.
+
+---
+
+**Pro tip:** Start with just `envcheck`. When you need more, the features are there. When you don't, they stay out of your way.
+
+Built with ☕, mild frustration, and the belief that developer tools should be both simple and powerful.

package/bin/envcheck.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * envcheck CLI entry point
+ * 
+ * Orchestrates the entire workflow:
+ * 1. Parse command-line arguments
+ * 2. Load ignore patterns
+ * 3. Scan codebase for files
+ * 4. Scan files for environment variable references
+ * 5. Parse .env.example file
+ * 6. Analyze and categorize issues
+ * 7. Format and display output
+ * 8. Exit with appropriate code
+ * 
+ * REPL Mode:
+ * - Run without arguments or with --repl/-r flag to start interactive mode
+ */
+
+import { run } from '../src/cli.js';
+import { startREPL } from '../src/repl.js';
+
+process.on('unhandledRejection', (reason) => {
+  const message = reason && reason.message ? reason.message : String(reason);
+  console.error(`Unhandled rejection: ${message}`);
+  process.exit(2);
+});
+
+process.on('uncaughtException', (error) => {
+  console.error(`Unhandled exception: ${error.message}`);
+  process.exit(2);
+});
+
+const args = process.argv.slice(2);
+
+// Check for REPL mode
+if (args.length === 0 || args.includes('--repl') || args.includes('-r')) {
+  // Remove --repl flag if present
+  const replArgs = args.filter(arg => arg !== '--repl' && arg !== '-r');
+  
+  // If no other args, start REPL
+  if (replArgs.length === 0) {
+    startREPL().catch(error => {
+      console.error(`REPL error: ${error.message}`);
+      process.exit(2);
+    });
+  } else {
+    // Run command normally
+    run(replArgs)
+      .then(exitCode => {
+        process.exit(exitCode);
+      })
+      .catch(error => {
+        console.error(`Fatal error: ${error.message}`);
+        process.exit(2);
+      });
+  }
+} else {
+  // Normal CLI mode
+  run(args)
+    .then(exitCode => {
+      process.exit(exitCode);
+    })
+    .catch(error => {
+      console.error(`Fatal error: ${error.message}`);
+      process.exit(2);
+    });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "envprobe",
+  "version": "1.0.0",
+  "description": "Zero-dependency CLI tool for validating environment variables across codebases",
+  "type": "module",
+  "bin": {
+    "envprobe": "bin/envcheck.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "benchmark": "node benchmarks/benchmark.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "cli",
+    "environment-variables",
+    "env",
+    "validation",
+    "dotenv",
+    "linter",
+    "env-check",
+    "environment",
+    "config",
+    "devops",
+    "ci-cd"
+  ],
+  "author": "Bitreon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RealBitreon/envprobe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RealBitreon/envprobe/issues"
+  },
+  "homepage": "https://github.com/RealBitreon/envprobe#readme",
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "fast-check": "^4.6.0"
+  }
+}

package/src/analyzer.js

@@ -0,0 +1,179 @@
+/**
+ * Issue Analyzer Module
+ * 
+ * Compares environment variable references from code against definitions
+ * in .env.example and categorizes issues into three types:
+ * - MISSING: Used in code but absent from .env.example
+ * - UNUSED: Defined in .env.example but never referenced
+ * - UNDOCUMENTED: Used and defined but lacking inline comments
+ */
+
+/**
+ * Analyzes environment variable usage and categorizes issues
+ * 
+ * @param {Array<{varName: string, filePath: string, lineNumber: number, pattern: string}>} references - Env var references from code
+ * @param {Array<{varName: string, hasComment: boolean, comment: string|null, lineNumber: number}>} definitions - Env var definitions from .env.example
+ * @returns {{missing: Array, unused: Array, undocumented: Array, summary: Object}} Analysis result
+ */
+export function analyzeIssues(references, definitions) {
+  // Group references by variable name for efficient lookup
+  const refsByVar = groupReferencesByVariable(references);
+  
+  // Create definition lookup map
+  const defByVar = createDefinitionMap(definitions);
+  
+  // Get unique variable names from both sources
+  const referencedVars = new Set(references.map(ref => ref.varName));
+  const definedVars = new Set(definitions.map(def => def.varName));
+  
+  // Detect MISSING variables (used in code but not in .env.example)
+  const missing = findMissing(referencedVars, definedVars, refsByVar);
+  
+  // Detect UNUSED variables (in .env.example but never used)
+  const unused = findUnused(definedVars, referencedVars, defByVar);
+  
+  // Detect UNDOCUMENTED variables (used and defined but no comment)
+  const undocumented = findUndocumented(referencedVars, definedVars, refsByVar, defByVar);
+  
+  // Calculate summary statistics
+  const summary = calculateSummary(missing, unused, undocumented, referencedVars, definedVars);
+  
+  return {
+    missing,
+    unused,
+    undocumented,
+    summary
+  };
+}
+
+/**
+ * Groups environment variable references by variable name
+ * 
+ * @param {Array<{varName: string, filePath: string, lineNumber: number, pattern: string}>} references
+ * @returns {Map<string, Array>} Map of variable name to array of references
+ */
+export function groupReferencesByVariable(references) {
+  const refsByVar = new Map();
+  
+  for (const ref of references) {
+    if (!refsByVar.has(ref.varName)) {
+      refsByVar.set(ref.varName, []);
+    }
+    refsByVar.get(ref.varName).push(ref);
+  }
+  
+  return refsByVar;
+}
+
+/**
+ * Creates a lookup map of definitions by variable name
+ * 
+ * @param {Array<{varName: string, hasComment: boolean, comment: string|null, lineNumber: number}>} definitions
+ * @returns {Map<string, Object>} Map of variable name to definition object
+ */
+export function createDefinitionMap(definitions) {
+  const defByVar = new Map();
+  
+  for (const def of definitions) {
+    defByVar.set(def.varName, def);
+  }
+  
+  return defByVar;
+}
+
+/**
+ * Finds MISSING variables (used in code but not in .env.example)
+ * 
+ * @param {Set<string>} referencedVars - Set of variable names used in code
+ * @param {Set<string>} definedVars - Set of variable names defined in .env.example
+ * @param {Map<string, Array>} refsByVar - Map of variable name to references
+ * @returns {Array<{varName: string, references: Array}>} Array of missing variable issues
+ */
+export function findMissing(referencedVars, definedVars, refsByVar) {
+  const missing = [];
+  
+  for (const varName of referencedVars) {
+    if (!definedVars.has(varName)) {
+      missing.push({
+        varName,
+        references: refsByVar.get(varName)
+      });
+    }
+  }
+  
+  // Sort by variable name for consistent output
+  return missing.sort((a, b) => a.varName.localeCompare(b.varName));
+}
+
+/**
+ * Finds UNUSED variables (defined in .env.example but never used)
+ * 
+ * @param {Set<string>} definedVars - Set of variable names defined in .env.example
+ * @param {Set<string>} referencedVars - Set of variable names used in code
+ * @param {Map<string, Object>} defByVar - Map of variable name to definition
+ * @returns {Array<{varName: string, definition: Object}>} Array of unused variable issues
+ */
+export function findUnused(definedVars, referencedVars, defByVar) {
+  const unused = [];
+  
+  for (const varName of definedVars) {
+    if (!referencedVars.has(varName)) {
+      unused.push({
+        varName,
+        definition: defByVar.get(varName)
+      });
+    }
+  }
+  
+  // Sort by variable name for consistent output
+  return unused.sort((a, b) => a.varName.localeCompare(b.varName));
+}
+
+/**
+ * Finds UNDOCUMENTED variables (used and defined but no inline comment)
+ * 
+ * @param {Set<string>} referencedVars - Set of variable names used in code
+ * @param {Set<string>} definedVars - Set of variable names defined in .env.example
+ * @param {Map<string, Array>} refsByVar - Map of variable name to references
+ * @param {Map<string, Object>} defByVar - Map of variable name to definition
+ * @returns {Array<{varName: string, references: Array, definition: Object}>} Array of undocumented variable issues
+ */
+export function findUndocumented(referencedVars, definedVars, refsByVar, defByVar) {
+  const undocumented = [];
+  
+  for (const varName of referencedVars) {
+    if (definedVars.has(varName)) {
+      const def = defByVar.get(varName);
+      if (!def.hasComment) {
+        undocumented.push({
+          varName,
+          references: refsByVar.get(varName),
+          definition: def
+        });
+      }
+    }
+  }
+  
+  // Sort by variable name for consistent output
+  return undocumented.sort((a, b) => a.varName.localeCompare(b.varName));
+}
+
+/**
+ * Calculates summary statistics for the analysis
+ * 
+ * @param {Array} missing - Array of missing variable issues
+ * @param {Array} unused - Array of unused variable issues
+ * @param {Array} undocumented - Array of undocumented variable issues
+ * @param {Set<string>} referencedVars - Set of variable names used in code
+ * @param {Set<string>} definedVars - Set of variable names defined in .env.example
+ * @returns {{totalMissing: number, totalUnused: number, totalUndocumented: number, totalReferences: number, totalDefinitions: number}}
+ */
+export function calculateSummary(missing, unused, undocumented, referencedVars, definedVars) {
+  return {
+    totalMissing: missing.length,
+    totalUnused: unused.length,
+    totalUndocumented: undocumented.length,
+    totalReferences: referencedVars.size,
+    totalDefinitions: definedVars.size
+  };
+}