envdoc-scan 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 takeaseatventure
+
+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,118 @@
+# envdoc-scan
+
+**Scan your codebase for environment-variable references and generate a `.env.example` template or a documentation table. Never let your `.env.example` drift again.**
+
+[![tests](https://img.shields.io/badge/tests-19%20pass-brightgreen)](#)
+[![npm](https://img.shields.io/npm/v/envdoc-scan)](https://npmjs.com/package/envdoc-scan)
+
+---
+
+## Why
+
+Every project has a `.env.example` that's supposed to list all the environment variables the app needs. In practice, it's always out of date — someone adds `process.env.NEW_THING` to the code and forgets to update the template. New contributors hit cryptic errors because they're missing a var.
+
+`envdoc` scans your source files for every environment-variable reference and tells you exactly:
+
+- **Which vars your code actually uses** (and where)
+- **Which vars are in your `.env.example` but no longer referenced** (dead config)
+- **Which vars are used in code but missing from `.env.example`** (undocumented)
+
+## Install
+
+```bash
+npm install -g envdoc-scan
+```
+
+Or use it directly with `npx`:
+
+```bash
+npx envdoc-scan
+```
+
+## Usage
+
+```bash
+# Print a .env.example template (default)
+envdoc-scan
+
+# Print a markdown documentation table
+envdoc-scan --markdown
+
+# Merge with your existing .env.example (preserves comments + defaults)
+envdoc-scan --existing .env.example
+
+# Flag vars in .env.example that are no longer in source
+envdoc-scan --existing .env.example --mark-unused
+
+# Output JSON (for CI checks or tooling)
+envdoc-scan src/ --json
+
+# Scan a specific directory
+envdoc-scan src/
+```
+
+### Output formats
+
+**`.env.example` (default):**
+```bash
+# Database connection string
+DATABASE_URL=postgres://localhost/mydb
+
+# Auth
+# (unused — not found in source)
+SECRET_KEY=changeme
+
+API_KEY=
+
+REDIS_URL=
+```
+
+**Markdown table:**
+
+| Variable | Default | Used | Location |
+|----------|---------|------|----------|
+| `DATABASE_URL` | postgres://localhost/mydb | yes | `sample.js:3` (+1) |
+| `SECRET_KEY` | changeme | no | — |
+| `API_KEY` | — | yes | `sample.js:2` |
+
+**JSON:**
+```json
+{
+  "DATABASE_URL": [{ "file": "config.js", "line": 12, "col": 25 }]
+}
+```
+
+## Supported patterns
+
+`envdoc` detects environment-variable access across multiple languages:
+
+| Language | Pattern |
+|----------|---------|
+| **Node / Bun** | `process.env.NAME`, `process.env['NAME']` |
+| **Python** | `os.environ.get('NAME')`, `os.getenv('NAME')`, `os.environ['NAME']` |
+| **Java** | `System.getenv("NAME")` |
+| **Ruby** | `ENV['NAME']` |
+| **Rust** | `env::var("NAME")` |
+| **Go** | `os.LookupEnv("NAME")` |
+
+## What it scans
+
+By default, `envdoc` scans these file types:
+
+`.js`, `.mjs`, `.cjs`, `.ts`, `.jsx`, `.tsx`, `.py`, `.java`, `.rb`, `.rs`, `.go`, `.sh`, `.bash`, `.yml`, `.yaml`
+
+It automatically skips: `node_modules`, `.git`, `vendor`, `dist`, `build`, `.next`, `target`, `__pycache__`, `.venv`, `venv`, `coverage`, `.cache`, and hidden directories.
+
+## CI integration
+
+Use `--json` to fail CI if your `.env.example` is missing vars:
+
+```bash
+# In your CI pipeline:
+envdoc --json > /tmp/scanned.json
+# ... diff against your committed .env.example
+```
+
+## License
+
+MIT © takeaseatventure

package/bin/envdoc.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+const { scanDirectory } = require('../lib/scan');
+const { readFile } = require('../lib/dotenv');
+const { merge, formatEnvExample, formatMarkdown } = require('../lib/format');
+
+function parseArgs(argv) {
+  const args = {
+    _: [],
+    format: 'env',        // 'env' | 'markdown' | 'json'
+    root: '.',
+    existing: null,       // path to existing .env.example to merge
+    markUnused: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') args.help = true;
+    else if (a === '--markdown' || a === '-m') args.format = 'markdown';
+    else if (a === '--json') args.format = 'json';
+    else if (a === '--env' || a === '-e') args.format = 'env';
+    else if (a === '--mark-unused') args.markUnused = true;
+    else if (a === '--existing') args.existing = argv[++i];
+    else if (a.startsWith('--root')) args.root = argv[++i];
+    else if (a.startsWith('-')) { /* ignore unknown */ }
+    else args._.push(a);
+  }
+  if (args._.length) args.root = args._[0];
+  return args;
+}
+
+const HELP = `envdoc — scan your codebase for environment-variable references
+and generate a .env.example template or a documentation table.
+
+USAGE
+  envdoc [options] [<path>]
+
+OPTIONS
+  -e, --env             Output a .env.example template (default)
+  -m, --markdown        Output a markdown documentation table
+  --json                Output JSON (name -> locations[])
+  --existing <file>     Merge with an existing .env / .env.example
+                        (preserves comments and known default values)
+  --mark-unused         Flag vars in the existing file that are no longer
+                        referenced in source
+  <path>                Root directory to scan (default: current dir)
+  -h, --help            Show this help
+
+EXAMPLES
+  envdoc                         # scan . and print a .env.example
+  envdoc --markdown              # print a markdown doc table
+  envdoc --existing .env.example # merge with your current template
+  envdoc src/ --json             # scan only src/, emit JSON
+
+Never let your .env.example drift again.`;
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { process.stdout.write(HELP + '\n'); return 0; }
+
+  const scanned = scanDirectory(args.root);
+  const existing = args.existing ? readFile(args.existing) : [];
+  const entries = merge(scanned, existing);
+
+  if (args.format === 'json') {
+    const obj = {};
+    for (const e of entries) obj[e.key] = e.locations || [];
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+    return 0;
+  }
+  if (args.format === 'markdown') {
+    process.stdout.write(formatMarkdown(entries) + '\n');
+    return 0;
+  }
+  process.stdout.write(formatEnvExample(entries, { markUnused: args.markUnused }));
+  return 0;
+}
+
+process.exit(main());

package/lib/dotenv.js

@@ -0,0 +1,53 @@
+'use strict';
+// dotenv.js — minimal .env / .env.example parser.
+// Reads KEY=VALUE lines and any leading comments so we can preserve them
+// when regenerating a template.
+
+const fs = require('fs');
+
+/**
+ * Parse a .env-format file into an ordered list of entries.
+ * @param {string} content
+ * @returns {Array<{key:string, value:string, comment:string, present:boolean}>}
+ */
+function parse(content) {
+  const lines = content.split('\n');
+  const out = [];
+  let pendingComment = '';
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) { pendingComment = ''; continue; }
+    if (line.startsWith('#')) {
+      // Accumulate comment lines; attach to the next key.
+      const text = line.replace(/^#\s?/, '');
+      pendingComment = pendingComment ? pendingComment + ' ' + text : text;
+      continue;
+    }
+    const eq = line.indexOf('=');
+    if (eq === -1) { pendingComment = ''; continue; }
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    // Strip surrounding quotes.
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (!/^[A-Z0-9_]+$/i.test(key)) { pendingComment = ''; continue; }
+    out.push({ key, value, comment: pendingComment, present: true });
+    pendingComment = '';
+  }
+  return out;
+}
+
+/**
+ * Read a .env file from disk, returning entries (or [] if missing).
+ */
+function readFile(filePath) {
+  try {
+    return parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+module.exports = { parse, readFile };

package/lib/format.js

@@ -0,0 +1,90 @@
+'use strict';
+// format.js — turn a scan result into a .env.example or a markdown table.
+
+/**
+ * Merge scanned vars with an existing .env.example's entries so comments
+ * and known defaults are preserved.
+ *
+ * @param {Map<string, Array>} scanned  - name -> locations[]
+ * @param {Array} existing               - [{key, value, comment, present}]
+ * @returns {Array} merged entries (ordered: existing first, then new scanned)
+ */
+function merge(scanned, existing) {
+  const seen = new Set();
+  const merged = [];
+  // Existing entries first (preserve order + comments).
+  for (const e of existing) {
+    const locs = scanned.get(e.key) || [];
+    merged.push({
+      key: e.key,
+      value: e.value,
+      comment: e.comment,
+      used: locs.length > 0,
+      locations: locs,
+    });
+    seen.add(e.key);
+  }
+  // Then newly-discovered vars not in the existing file.
+  const sorted = Array.from(scanned.keys()).sort();
+  for (const key of sorted) {
+    if (seen.has(key)) continue;
+    merged.push({
+      key,
+      value: '',
+      comment: '',
+      used: true,
+      locations: scanned.get(key),
+    });
+  }
+  return merged;
+}
+
+/**
+ * Render merged entries as a .env.example file.
+ * @param {Array} entries
+ * @param {object} opts - { markUnused:true }
+ * @returns {string}
+ */
+function formatEnvExample(entries, opts) {
+  opts = opts || {};
+  const lines = [];
+  for (const e of entries) {
+    if (e.comment) {
+      lines.push('# ' + e.comment);
+    }
+    if (opts.markUnused && e.used === false) {
+      lines.push('# (unused — not found in source)');
+    }
+    const value = e.value !== '' ? e.value : '';
+    lines.push(`${e.key}=${value}`);
+    lines.push('');
+  }
+  return lines.join('\n').replace(/\n+$/, '\n');
+}
+
+/**
+ * Render merged entries as a markdown documentation table.
+ * @param {Array} entries
+ * @returns {string}
+ */
+function formatMarkdown(entries) {
+  const lines = [];
+  lines.push('# Environment Variables');
+  lines.push('');
+  lines.push('| Variable | Default | Used | Location |');
+  lines.push('|----------|---------|------|----------|');
+  for (const e of entries) {
+    const def = e.value || '—';
+    const used = e.used === false ? 'no' : 'yes';
+    const loc = e.locations && e.locations.length
+      ? '`' + e.locations[0].file + ':' + e.locations[0].line + '`' +
+        (e.locations.length > 1 ? ` (+${e.locations.length - 1})` : '')
+      : '—';
+    const row = `| \`${e.key}\` | ${def} | ${used} | ${loc} |`;
+    lines.push(row);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+module.exports = { merge, formatEnvExample, formatMarkdown };

package/lib/scan.js

@@ -0,0 +1,147 @@
+'use strict';
+// scan.js — find environment-variable references in source files.
+//
+// Supports common patterns across languages:
+//   process.env.NAME          (Node/Bun)
+//   process.env['NAME']       (Node, bracket form)
+//   os.environ['NAME']        (Python)
+//   os.environ.get('NAME')    (Python)
+//   os.getenv('NAME')         (Python)
+//   System.getenv("NAME")     (Java)
+//   ENV['NAME']               (Ruby)
+//   env::var("NAME")          (Rust)
+//   os.LookupEnv("NAME")      (Go)
+//
+// Also reads an existing .env / .env.example to carry over comments and
+// mark which vars are already documented.
+
+const fs = require('fs');
+const path = require('path');
+
+// (accessor prefix) (optional quote) NAME (closing bracket or word boundary)
+const PATTERNS = [
+  // process.env.NAME  and  process.env['NAME']
+  /process\.env(?:\[['"]([A-Z0-9_]{2,})['"]\]|\s*\.\s*([A-Z0-9_]{2,}))/g,
+  // os.environ['NAME'] / os.environ.get('NAME') / os.getenv('NAME')
+  /os\.environ(?:\.get)?\(\s*['"]([A-Z0-9_]{2,})['"]\s*\)|os\.environ\[['"]([A-Z0-9_]{2,})['"]\]/g,
+  /os\.getenv\(\s*['"]([A-Z0-9_]{2,})['"]\s*\)/g,
+  // System.getenv("NAME")
+  /System\.getenv\(\s*"([A-Z0-9_]{2,})"\s*\)/g,
+  // ENV['NAME']  (Ruby)
+  /\bENV\[['"]([A-Z0-9_]{2,})['"]\]/g,
+  // env::var("NAME")  (Rust)
+  /env::var\(\s*"([A-Z0-9_]{2,})"\s*\)/g,
+  // os.LookupEnv("NAME")  (Go)
+  /os\.LookupEnv\(\s*"([A-Z0-9_]{2,})"\s*\)/g,
+];
+
+// File extensions we scan, by default.
+const DEFAULT_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx',
+  '.py',
+  '.java',
+  '.rb',
+  '.rs',
+  '.go',
+  '.sh', '.bash',
+  '.yml', '.yaml',
+]);
+
+// Directories we never descend into.
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', 'vendor', 'dist', 'build', '.next', '.nuxt',
+  'target', '__pycache__', '.venv', 'venv', 'env', '.env',
+  'coverage', '.cache', '.turbo', '.svelte-kit',
+]);
+
+/**
+ * Walk a directory tree, returning source file paths to scan.
+ * @param {string} root
+ * @param {object} opts - { extensions?: Set<string> }
+ * @returns {string[]}
+ */
+function listSourceFiles(root, opts) {
+  opts = opts || {};
+  const exts = opts.extensions || DEFAULT_EXTENSIONS;
+  const out = [];
+  if (!fs.existsSync(root)) return out;
+  const stat = fs.statSync(root);
+  if (stat.isFile()) return [root];
+  _walk(root, exts, out);
+  return out;
+}
+
+function _walk(dir, exts, out) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (IGNORE_DIRS.has(e.name)) continue;
+      // Skip hidden directories.
+      if (e.name.startsWith('.')) continue;
+      _walk(path.join(dir, e.name), exts, out);
+    } else if (e.isFile()) {
+      if (exts.has(path.extname(e.name).toLowerCase())) {
+        out.push(path.join(dir, e.name));
+      }
+    }
+  }
+}
+
+/**
+ * Scan a single file's content for env-var references.
+ * @param {string} content
+ * @returns {Array<{name:string, line:number, col:number}>}
+ */
+function scanContent(content) {
+  const hits = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const re of PATTERNS) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(line)) !== null) {
+        // Pick the first defined capture group (patterns have alternations).
+        const name = m[1] || m[2] || m[3] || null;
+        if (name) {
+          hits.push({ name, line: i + 1, col: m.index + 1 });
+        }
+      }
+    }
+  }
+  return hits;
+}
+
+/**
+ * Scan an entire directory, returning a map of varName -> locations[].
+ * @param {string} root
+ * @param {object} opts
+ * @returns {Map<string, Array<{file:string, line:number, col:number}>>}
+ */
+function scanDirectory(root, opts) {
+  opts = opts || {};
+  const files = listSourceFiles(root, opts);
+  const result = new Map();
+  for (const file of files) {
+    let content;
+    try { content = fs.readFileSync(file, 'utf8'); }
+    catch { continue; }
+    const hits = scanContent(content);
+    for (const h of hits) {
+      if (!result.has(h.name)) result.set(h.name, []);
+      result.get(h.name).push({ file: path.relative(root, file), line: h.line, col: h.col });
+    }
+  }
+  return result;
+}
+
+module.exports = {
+  scanContent,
+  scanDirectory,
+  listSourceFiles,
+  PATTERNS,
+  DEFAULT_EXTENSIONS,
+  IGNORE_DIRS,
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "envdoc-scan",
+  "version": "0.1.0",
+  "description": "Scan your codebase for environment-variable references and generate a .env.example template and/or a documentation table. Never let your .env.example drift again.",
+  "license": "MIT",
+  "author": "takeaseatventure",
+  "keywords": [
+    "env",
+    "environment",
+    "variables",
+    "dotenv",
+    "example",
+    "documentation",
+    "cli",
+    "scanner",
+    "audit",
+    "envdoc"
+  ],
+  "homepage": "https://github.com/takeaseatventure/envdoc-scan#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/takeaseatventure/envdoc-scan.git"
+  },
+  "bin": {
+    "envdoc-scan": "./bin/envdoc.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "bugs": {
+    "url": "https://github.com/takeaseatventure/envdoc-scan/issues"
+  }
+}